The transaction banking payment feature of the Pismo platform provides functionalities that help you perform different payment transactions such as posting credit or debit payments, force transfer payments, and multi-leg payments. Key functions include:

• Post payment: Use this feature to post both credit and debit transactions to an account. Additionally, you can initiate force transfer payments.
• Post multi-leg payment: Execute multiple payment transactions simultaneously. Rather than submitting individual payment requests, you can consolidate different payment types (credit, debit, or a combination of both) into a single request for enhanced efficiency and convenience.

Post payment

The Pismo platform features a Post payment API that enables transaction banking account holders to transfer funds, and conduct cash-in and cash-out transactions. This API leverages many features of the Core payments API, but is particularly tailored for transaction banking clients..

Post payment enables the posting of debits and credits to an account and facilitating fund transfers between them. Follow the guidelines below to use the API for posting credits, debits, earmark payments, or conducting fund transfers. For details about how the Payments API works in general, see Payments and transfers.

Post credit payments

When initiating credit payments, ensure that you include a credit object containing a valid processing_code and an external_account_id. These attributes identify the target account and the financial transaction type. The following table describes these fields:

Post debit payments

Likewise, for debit payments, you must provide values for processing_code and external_account_id within the debit object. Note that if the debit object includes an earmark_id value, the debit amount is deducted directly from the earmark balance. The earmark_id indicates the ID the earmarked balance from which the amount is withdrawn, the Earmark ID is generated by the Create Earmark endpoint.

Execute fund transfer

To execute fund transfers, include both credit and debit objects. If you specify an earmark_id value within the debit object, the transferred amount is deducted directly from the earmark balance.

Execute force transfers

To execute force transfers, include both a credit and a debit object, and set the force_post field to true. Note that force transfers from an earmark balance are not supported.

If an account has a status that prevents force operations, the transfer will fail. For more information, see Manage account statuses.

Reasons that restrict force credit or debit operations are:

To get a list of available reasons for a specific account status, use the List account status reasons endpoint.

For sample payloads for each of the aforementioned payment types, refer to the examples provided in Post payment endpoint.

Post multi-leg payment

The Pismo platform enables you to execute multi-leg payments. Each leg of a multi-leg payment represents a distinct payment type, categorized as either credit or debit. Use the Post multi-leg payment endpoint to initiate multi-leg payment requests. When making such requests, make sure they include at least two legs (either a credit or debit object).

📘

You cannot use Post multi-leg payment to transfer credit and debit leg payments to the same account for identical amounts. For such situations, send Post payment requests instead.

Tracking ID requirement

When using the Post multi-leg payment endpoint, you must pass a tracking ID. It is used to generate a child tracking ID for each leg. These IDs are created by adding a control suffix to the original tracking ID. Each child tracking ID is then hashed to guarantee a unique identifier. For more information about tracking ID, see the description in the tracking_id field of Post multi-leg payment.

Force payment restrictions

In scenarios where force_post is set to true, any reason-based force payment restrictions on the account will result in a failed force payment operation. These restrictions apply to both credit and debit operations. Use the List account status reasons endpoint to view the corresponding reason IDs. Forced transfers from an earmark balance are not supported.

If an account has a status that prevents force operations, the payment will fail. For more information, see Manage account statuses.

Error handling mechanism

During the processing of a payment request, should any leg encounter an error, the Pismo platform enforces an error-handling mechanism called rollback. Rollback is designed to safeguard data integrity by reversing an entire payment request in the event of one or more leg failures. It is a resource-intensive mechanism that leaves traces of reversal transactions to compensate (offset) for successfully executed legs. To minimize rollback occurrences, thorough validation is conducted upon receiving each payment request. Additionally, the platform proactively alerts you to potential failures upon detecting invalid inputs.

Error response structure

When validation errors occur within a request, the API returns a structured error response that has two components:

Standard error message: For example, the error code WMLP0005 warns users about invalid inputs without providing specific leg-related error details. This error typically happens when you reuse a tracking_id.

List of leg-specific errors: In addition to generic error messages, a response payload may include detailed lists of leg-specific errors. In certain situations, an error can be related to an entire request, and not limited to leg-specific error (such as when a request exceeds the maximum allowable number of legs). In such cases, the standard error response containing only code and message attributes is provided. Refer to the examples in the Post multi-leg payment endpoint for various error types and their respective error codes.

How to use Post multi-leg payment API

Consider a scenario in which your account has a balance of $1000, and you wish to initiate a payment request with three legs: two debit legs (one for $100, another for $200) and one credit leg for $600. Here are the account details:

{
    "account_id": 150317653,
    "division_code": "my-division-code-1705083775718",
    "program_id": 10768,
    "available_balance": 1000,
    "earmark_balance": 0,
    "overdraft_limit": 0,
    "book_balance": 1000,
    "value_dated_balance": 1000,
    "children": [],
    "status": "NORMAL",
    "external_account_id": "df4c54fe-776e-4c49-bd2d-d03a89013218",
    "currency_numeric_code": "840",
    "currency_alphabetic_code": "USD",
    "document_number": "27948365",
    "account_creation_datetime": "2024-03-01T16:25:13.000Z"
}

To initiate the multi-leg payment , use the Post multi-leg payment endpoint. The following is a sample request for this operation:

curl --location 'https://sandbox.pismolabs.io/corporate/v1/payments/multileg' \
--header 'Content-Type: application/json' \
--header '<your_token>' \
--data '{
  "tracking_id": "f85fd6e1-8b22-4850-b350-a2768dc443732233",
  "debits": [
    {
      "amount": 100,
      "currency": "USD",
      "external_account_id": "df4c54fe-776e-4c49-bd2d-d03a89013218"
    },
    {
      "amount": 200,
      "currency": "USD",
      "external_account_id": "df4c54fe-776e-4c49-bd2d-d03a89013218"
    }
  ],
  "credits": [
    {
      "amount": 600,
      "currency": "USD",
      "external_account_id": "df4c54fe-776e-4c49-bd2d-d03a89013218"
    }
  ]
}'

📘

Note that tracking_id must be unique; otherwise a validation error with WMLP0005 will occur.

Upon successful execution, the API returns the following response payload to confirm the successful processing of your request:

{
    "debits": [
        {
            "external_account_id": "df4c54fe-776e-4c49-bd2d-d03a89013218",
            "amount": 100,
            "currency": "USD",
            "force_post": false,
            "skip_account_date_validation": false
        },
        {
            "external_account_id": "df4c54fe-776e-4c49-bd2d-d03a89013218",
            "amount": 200,
            "currency": "USD",
            "force_post": false,
            "skip_account_date_validation": false
        }
    ],
    "credits": [
        {
            "external_account_id": "df4c54fe-776e-4c49-bd2d-d03a89013218",
            "amount": 600,
            "currency": "USD",
            "force_post": false,
            "skip_account_date_validation": false
        }
    ],
    "tracking_id": "f85fd6e1-8b22-4850-b350-a2768dc443732233",
    "metadata": null
}

You can optionally use Get transaction banking account info to retrieve and display the complete result of this transaction. As shown in the response below, the payment request comprising two debit legs totaling $300 and one credit leg of $600 results in an updated account balance of $1300.

{
    "account_id": 150317653,
    "division_code": "my-division-code-1705083775718",
    "program_id": 10768,
    "available_balance": 1300,
    "earmark_balance": 0,
    "overdraft_limit": 0,
    "book_balance": 1300,
    "value_dated_balance": 1300,
    "children": [],
    "status": "NORMAL",
    "external_account_id": "df4c54fe-776e-4c49-bd2d-d03a89013218",
    "currency_numeric_code": "840",
    "currency_alphabetic_code": "USD",
    "document_number": "27948365",
    "account_creation_datetime": "2024-03-01T16:25:13.000Z"
}