About PismoContact Us

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 that affects_balance is now deprecated and is replaced by affects_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
}

Forced operation vs. adjustment

Both a forced operation and an adjustment directly impact the amount of money in the customer account either by adding or subtracting funds, but there are important functional differences between them.

Forced operationAdjustment
A forced operation is an anticipated operation that happens in a regular operational scenario. For example, it can be a cashback credit or a transaction fee.An adjustment is a tool for you to adjust values when something outside of the normal operational scenarios happens. For example, it can be used to correct minor inconsistencies in values due to different rounding numbers methods from one platform to another.
A request to the force endpoint generates an authorization with a new authorization identifier, which in turn generates a transaction and triggers all expected events and data workflows.A request to the adjustment endpoint does not generate an authorization but generates an adjustment with a new adjustment identifier.
A forced operation is implemented using a processing_code.An adjustment is implemented using an adjustment_type.
A forced operation does not validate account status, account balance, or flex controls.An adjustment does not validate account status or flex controls but can be configured to validate account balance.
A processing_code can be configured to integrate with the Pismo processes to perform certain rate calculations.An adjustment_type can be configured in a variety of ways to customize the flow, for example, whether an adjustment affects credit limit, impacts statement balance, or is sent to accounting.
The Force operation API is recommended for new implementations and is slated for future enhancements.The Adjustments API is supported in maintenance mode.

For additional information on forced operations, see Force operation.

Related pages

API reference / Get adjustment types
API reference / Create adjustment
API reference / Get adjustment
API reference / Get reversal types

Updated 3 months ago