Adjustments overview
Learn how to use adjustments to manage account balances.
You can either add or remove funds from an account balance by posting an adjustment event. For example, you can use this kind of event to resolve balance inconsistencies originating from duplicated transactions, to return money to your customers in case of tax deals, to credit an account when a payment transaction failed to be delivered, or to give cash back. You can also post adjustments to your customer's timeline.
The adjustments functionality in the Pismo platform:
- Does not launch an authorization.
- Does not do account status validation.
- Can impact the balance of the customer's portfolio (configurable).
- Can launch a timeline event (configurable).
- Allows you to configure whether to validate balance in an account (for example, if the issuer configures to skip validation, even if there's not enough balance in an account to perform an adjustment debit of $10, the adjustment is still performed).
Adjustments directly impact the amount of money in the customer account, either by adding or subtracting funds. Though you can use adjustments to solve problems quickly, you should use it with care.
The Adjustments API allows you to perform two types of operations:
- Adjustment, which directly posts a transaction to an account.
- Reversal, which reverses an existing transaction to perform a one-time correction.
Adjustments
Get all adjustment types
Before you issue a POST to create an adjustment, you might want to list all adjustment types available to your program. To retrieve all adjustment types available for posting, issue a GET request to the following endpoint. For full details, see Get adjustment types.
GET <URL>adjustments/v1/types
Sample response
[
{
"id": 318,
"code": 98318,
"org_id": "TN-Tenant",
"description": "Promotional credit",
"affects_credit_limit": false,
"is_sent_to_timeline": false,
"validate_balance": true,
"visible": null,
"transaction_type": {
"id": 1010,
"description": "Debit adjustment",
"is_credit": false
},
"installment_transaction_type_id": null
}
]
The response indicates the id
and code
of the adjustment type, which you need to know before creating an adjustment.
- The
id
is an automatic sequential number that is different between environments.- You can define the
code
at the time of registration, so you can have the hardcoded code that works in any environment if you choose.
The response also indicates:
- Whether the transaction to be posted impacts the credit limit (
affects_credit_limit
). Note thataffects_balance
is now deprecated and is replaced byaffects_credit_limit
. - The
transaction_type
determines whether the transaction is debit or credit (is_credit
). - Whether to post an event to the timeline (
is_sent_to_timeline
).
Create adjustment
To create an adjustment, issue a POST to the following endpoint. Along with the required account_id
, amount
, and event_date
parameters, pass the code
(or id
) of the adjustment type in the adjustment_type
object. You can enrich your payload by adding a soft_descriptor
, description
, and additional comprehensive information for your end user in thetimeline_metadata
. For full details, see Create adjustment.
POST <URL>adjustments/v1/adjustments
Sample request
{
"account_id": 24154947,
"amount": 130.00,
"adjustment_type": {
"code": 98318,
"is_sent_to_timeline":true
},
"description": "This credit is issued to the customer because they won a lottery.",
"timeline_metadata": {
"field_to_appear_on_timeline": "any value entered"
}
}
Sample response
{
"id": 484932,
"account_id": 24154947,
"authorization_id": null,
"amount": 130.0,
"event_date": "2019-08-24T14:15:22Z",
"soft_descriptor": null,
"description": "This credit is issued to the customer because they won a lottery.",
"adjustment_type": {
"id": 123,
"code": 98318,
"org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
"description": "Fee chargeback",
"affects_credit_limit": true,
"is_sent_to_timeline": true,
"transaction_type": true
},
"details": {
"id": 0,
"requester_email": "[email protected]",
"creation_date_time": "2019-08-24",
"correlation_id": "807686c4-116c-44b3-a01c-b14b50e31bcc",
"transactions": []
},
"timeline_metadata": {
"field_to_appear_on_timeline": "any value entered"
}
}
Get an adjustment by ID
To get all details from a previously defined adjustment, you need the adjustment ID to issue a GET request to the following endpoint. For full details, see Get adjustment.
GET <URL>adjustments/v1/adjustments/{adjustmentId}
Sample response
{
"id": 484932,
"account_id": 24154947,
"authorization_id": null,
"amount": 130.0,
"event_date": "2019-08-24T14:15:22Z",
"soft_descriptor": null,
"description": "This credit is issued to the customer because they won a lottery.",
"adjustment_type": {
"id": 123,
"code": 98318,
"org_id": "a40f5d1f-d889-42e9-94ea-b9b33585fc6b",
"description": "Fee chargeback",
"affects_credit_limit": true,
"is_sent_to_timeline": true,
"transaction_type": true
},
"details": {
"id": 0,
"requester_email": "[email protected]",
"creation_date_time": "2019-08-24",
"correlation_id": "807686c4-116c-44b3-a01c-b14b50e31bcc",
"transactions": []
},
"timeline_metadata": {
"field_to_appear_on_timeline": "any value entered"
}
}
Reversals
Most adjustments available to your program have a corresponding reversal event.
Get all reversal types
To retrieve all reversal types available for posting, call the following GET endpoint. For details, see Get reversal types.
GET <URL>adjustments/v1/reversals-types
Sample response
[
{
"id": 1,
"fromTransactionType": {
"id": 0,
"description": "string",
"is_credit": true
},
"adjustmentType": {
"id": 1,
"org_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"description": "string",
"affects_credit_limit": true,
"is_sent_to_timeline": true,
"transaction_type": true
}
}
]
Create reversal
Every reversal has its configuration linked to an adjustment type. To create a reversal, issue a POST request to the following endpoint.
POST <URL>/adjustments/v1/reversals
Enter the id
of the transaction that is to be reversed and the amount
, since the reversal can be done partially.
Sample request
{
"transaction": {
"id": 127
},
"amount": 10
}
Sample response
{
"id": 3284,
"amount": 10,
"transaction": {
"id": 127,
"authorization_id": 2,
"network_authorization_id": null,
"org_id": "08102A0B-D4F8-42A2-8B0E-2052D05577D7",
"account_id": 457,
"transaction_type": {
"id": 101,
"description": "COMPRA A VISTA",
"is_credit": false
},
"amount": 323.64,
"event_date": "2015-11-01T00:00:00.000",
"soft_descriptor": null,
"installment": null
},
"details": {
"id": 672826,
"requester_email": null,
"creation_date_time": "2022-02-08T15:46:30.414Z",
"correlation_id": "84829f18-c25b-9208-aca7-ea10536ad7ef",
"transactions": null
},
"type": null,
"is_sent_to_timeline": null,
"revert_related_transactions": false
}
The reversal assigns the same authorization ID or network authorization ID to the new transaction that is to be posted.
Get a reversal by ID
To retrieve a reversal by ID, call the following GET endpoint.
GET <URL>/adjustments/v1/reversals/{reversalId}
Sample response
{
"id": 3284,
"amount": 10.00,
"transaction": {
"id": 127,
"authorization_id": 2,
"network_authorization_id": null,
"org_id": "08102A0B-D4F8-42A2-8B0E-2052D05577D7",
"account_id": 457,
"transaction_type": {
"id": 101,
"description": "COMPRA A VISTA",
"is_credit": false
},
"amount": 323.64,
"event_date": "2015-11-01T00:00:00.000",
"soft_descriptor": null,
"installment": null
},
"details": {
"id": 672826,
"requester_email": null,
"creation_date_time": "2022-02-08T15:46:30.414Z",
"correlation_id": "84829f18-c25b-9208-aca7-ea10536ad7ef",
"transactions": [
{
"id": 674049,
"transaction": {
"id": 37395298,
"authorization_id": 2,
"network_authorization_id": null,
"org_id": "08102A0B-D4F8-42A2-8B0E-2052D05577D7",
"account_id": 457,
"transaction_type": {
"id": 503,
"description": "CANCELAMENTO DE COMPRA",
"is_credit": true
},
"amount": 10.00,
"event_date": "2022-02-08T12:46:30.000",
"soft_descriptor": "CANCELAMENTO DE COMPRA",
"installment": null
},
"adjustment_type": {
"id": 1,
"code": null,
"org_id": "08102A0B-D4F8-42A2-8B0E-2052D05577D7",
"description": "CANCELAMENTO DE COMPRA",
"affects_credit_limit": true,
"is_sent_to_timeline": false,
"validate_balance": null,
"visible": null,
"transaction_type": {
"id": 503,
"description": "CANCELAMENTO DE COMPRA",
"is_credit": true
},
"installment_transaction_type_id": null
},
"status": "CREATED"
}
]
},
"type": null,
"is_sent_to_timeline": null,
"revert_related_transactions": false
}
Related pages
API reference / Get adjustment types
API reference / Create adjustment
API reference / Get adjustment
API reference / Get reversal types
Updated about 1 month ago