Payment methods

The Payment methods API is the enhanced application interface for managing platform operations, which are operations such as bank transfers and payments that don’t involve card networks like Visa and Mastercard. The Payment methods API offers flexible payments and authorization processes to support different business models. The endpoints in this API are dedicated to specific types of operations and are scaled to simplify payloads and improve performance. The API supports advanced features such as external authentication, pre-authorization, and configuration options.

📘

The Payment methods API is the recommended approach for any new deployments. It offers enhanced features that streamline processes and function differently from the Transfer funds and Cancel transfer endpoints that are described in the Payments and transfers guide. All new feature developments will be available only in the Payment methods API. For more information, contact your Pismo representative.

The Payment methods API includes the following endpoints.

• Request authorization to request a new authorization and cancel or confirm an existing authorization.
• The following endpoints to manage cash-in, cash-out, and transfer operations.
  • Create cash-in or cash-out
  • Cancel cash-in or cash-out
  • Confirm pre-authorized cash-in or cash-out
  • Create transfer
  • Cancel transfer
  • Confirm pre-authorized transfer
• All configuration endpoints in the following sections.
  • Payment method configs to manage payment methods configurations.
  • Payment method acceptances to manage acceptance configurations for processing code operations.

Payment and authorization

You can create platform operations such as cash-in, cash-out, cancellations, pre-authorizations, confirmations, denied authorizations, and peer-to-peer (p2p) transfers.

• To create a cash-in or cash-out operation on the indicated account, use the Create cash-in or cash-out endpoint. The type of operation depends on the processing code (credit for cash-in and debit for cash-out).
• To make transfers between two Pismo accounts, use the Create transfer endpoint.

You can also mark both of these operation types for pre-authorization by setting the pre_authorization parameter to true and then confirm pre-authorized operation.

Cancel operation

Every authorization is subject to partial or total cancellation. To cancel authorizations that have been successfully carried out and approved on the platform, use the following endpoints according to the type of original operation to be canceled.

• Cancel cash-in or cash-out
• Cancel transfer

Confirm pre-authorized operation

When you mark an operation for pre-authorization by setting the pre_authorization parameter to true, you need to confirm it so that the platform can create the transaction corresponding to this authorization.

• Confirm pre-authorized cash-in or cash-out
• Confirm pre-authorized transfer

There are three scenarios for confirming a pre-authorization.

• Debit pre-authorization (cash-out): the financial impact occurs during the pre-authorization, and the confirmation finalizes the operation and creates the transaction.

• Credit pre-authorization (cash-in): the financial impact occurs only during the confirmation, avoiding financial loss if the confirmation is not executed, preventing anyone who will receive the money from moving it into the account before the confirmation.

• Transfer pre-authorization

Authorization categories

The new endpoints support new authorization concepts and features. At the end of the operation authorization flow, the platform generates the following categories of authorizations and reflects them in the platform-authorization-1 event.

• AUTHORIZATION - a cash-in, cash-out, or transfer authorization was carried out successfully.
• CANCELLATION - a cash-in, cash-out, or transfer authorization was successfully canceled
• PARTIAL_CANCELLATION - the approved authorization refers to a partial cancellation of a previously approved operation.
• DENIED - the authorization operation cannot be approved.
• DENIED_CANCELLATION - the cancellation operation cannot be approved.
• CONFIRMATION - the confirmation was authorized successfully.

Validation results array

The transaction authorization flow on the Pismo platform goes through a series of validations to ensure that a financial transaction can be approved. During this flow, the platform validates data associated with the operation such as the account information, flexible transaction controls, balances and limits, anti-fraud and external validations, and various configurations.

Each financial transaction operation returns a validation results array in the response. The array contains details of each validation step taken during the authorization process. Each validation within the authorization flow generates a result with one of the following statuses: APPROVED, SKIPPED, or REJECTED. If there are any denied entries in the array, this results in a denied authorization.

In the following example, the array contains the validation that is approved by anti-fraud and the validation that is rejected by ledger. In this example, the operation is denied.

"validation_results": [
    {
        "name": "ANTI_FRAUD",
        "status": "APPROVED",
        "reason": "ANTI_FRAUD_APPROVED",
        "description": "Authorization passed anti-fraud evaluation.",
        "additional_data": {}
    },
    {
        "name": "LEDGER",
        "status": "REJECTED",
        "reason": "LEDGER_INSUFFICIENT_FUNDS",
        "description": "The authorization amount is greater than the account available limit.",
        "additional_data": {
            "denial_code": "LE003",
            "response_code": "04"
        }
    }
]

For details, see Authorization validation rules for platform operations.