v1

latestOpenAPI 3.1.0Copyright Pismo2026-07-247702,7523.1 MB

Payment methods

Create cash-in or cash-out

Create a cash-in or cash-out payment operation. The type of operation depends on the processing code (credit for cash-in and debit for cash-out).

For cash-in operations, the processing code must be of credit type. When creating a processing code, ensure that the balance_impact is 1 (credit).
For cash-out operations, the processing code must be of debit type. When creating a processing code, ensure that the balance_impact is -1 (debit).

With this endpoint, you have the following additional options.

Specify the authentication method and details.
Set pre_authorization to true for operations that require additional confirmation and then call the Confirm pre-authorized cash-in or cash-out endpoint.
Set validation_rules to control the rules in this flow, such as disabling a rule, changing the response code and denial code, and forcing a rule.

Refer to the Payment methods and Payment configurations guides for additional information.

This endpoint generates a Platform authorization created event.

Note: This is a PCI endpoint, use the https://gw-pci.pismolabs.io environment.

post/payment-methods/v2/payments

Request body

account_idinteger required

Account ID

beneficiary_idstring

Beneficiary ID. This ID created when the Register beneficiary endpoint is called.

amountnumber double required

Fee amount.

currency_codestring

ISO-4217 alphabetic or numeric (3 characters) authorization currency code. For example, either BRL or 986 for Brazilian real. If you don't provide the currency, the platform uses the currency registered in the Pismo hierarchy (first looking at the account, then program, and then Org levels).

processing_codestring required

Processing code for the debit transaction.

If split_transaction is false (the default), each installment payment is recorded as one debit transaction equal to the installment amount minus the discount, and processing_code is the processing code for that transaction.

If split_transaction is true, each installment payment is recorded as two transactions: a debit transaction for the installment amount and a credit transaction for the discount. In this case, processing_code is the processsing code for the debit transaction, and second_processing_code is the processing code for the credit transaction.

tracking_idstring required

Customer created tracking ID. Must consist of alphanumeric characters (a-z, A-Z, 0-9), hyphens (-), and colons (:), with a length from 1 to 128. The Pismo platform uses this field to implement idempotency and prevent duplicates.

descriptionstring

Challenge result

metadatastring

Any data object with key/value pairs. No limit on length.

Note: This field must not be used to send Personally Identifiable Information (PII), Payment Card Industry (PCI) data, or any sensitive/regulated information. Metadata fields are intended for operational, non-sensitive data only. For sensitive data, use the specific parameters designed for that purpose. For more information, refer to Get started with Pismo APIs.

payment_datetimestring date-time

Date and time of the payment. Specifying a payment_datetime value impacts the account balance history. Notes:

The payment datetime is in ISO 8601 format.
You can backdate payments a maximum of 390 calendar days. You can postdate payments a maximum of 10 calendar days.

pre_authorizationboolean

If set to true, this flag indicates that the operation is pre-authorized and requires additional confirmation.

validation_rulesValidationRules

Rules that determine which validations are executed during the payment process. Available validation rules:

LEDGER
ACCOUNT_STATUS
FLEX_CONTROLS
RATES

force is only supported for LEDGER. override is supported for ACCOUNT_STATUS, FLEX_CONTROLS, and RATES.

Example request

{
  "account_id": 6912345,
  "beneficiary_id": "97c96d96-9b87-404b-88e5-287f2b0e6e0a",
  "amount": 215,
  "currency_code": "BRL",
  "processing_code": "99066",
  "tracking_id": "3368328d-e4c6-4c75-99a9-9d59f3501d8c",
  "authentication": {
    "method": "otp",
    "parameters": {
      "device_id": "abc",
      "token": "123456",
      "user_id": "123456789"
    }
  },
  "description": "Challenge expired",
  "metadata": "{ \"key\": \"value\"}",
  "payment_datetime": "2023-03-10T19:05:56.743Z",
  "validation_rules": {
    "ACCOUNT_STATUS": {
      "override": false
    },
    "LEDGER": {
      "force": false
    },
    "FLEX_CONTROLS": {
      "override": true
    },
    "RATES": {
      "override": true
    }
  },
  "authorization_validations": {
    "is_device_registered": true,
    "associated_ids": {
      "payment_id": "319d00f5-48de-4c71-ad47-40b1e9c4e37f",
      "origin_id": "CUSTOM_ORIGIN"
    }
  },
  "original_authorization": {
    "id": 101,
    "type": "NETWORK"
  }
}

Response

Request was processed successfully, existing authorization with the corresponding tracking_id returned.

tracking_idstring required

account_idinteger

Account ID

response_codestring required

Network two-digit response code. For example: 00 = approve, 51 = insufficient funds, 57 = card not active, 96 = system failure, etc. For more information, see Validation codes for authorization events. If approve = false, you can use this value to respond to the network.

denial_codestring

Authorization denial code

Example response

{
  "tracking_id": "634c43f2-5b7e-4a80-81c7-e6a7d5edc7fe",
  "account_id": 456,
  "amount": 1000,
  "response_code": "00",
  "denial_code": "LE003",
  "validation_results": [
    {
      "name": "ACCOUNT",
      "status": "APPROVED",
      "reason": "ACCOUNT_FOUND",
      "description": "Account was found.",
      "additional_data": {
        "account_id": 2417
      }
    },
    {
      "name": "ACCEPTANCE",
      "status": "APPROVED",
      "reason": "ACCEPTANCE_FOUND",
      "description": "Payment methods acceptances were found."
    },
    {
      "name": "CONFIG",
      "status": "APPROVED",
      "reason": "CONFIG_FOUND",
      "description": "Payment methods configuration was found."
    },
    {
      "name": "PAYMENT_DATE",
      "status": "SKIPPED",
      "reason": "PAYMENT_DATE_SKIPPED",
      "description": "Payment date validation was skipped.",
      "additional_data": {
        "cause": "Payment date not present."
      }
    },
    {
      "name": "PLATFORM_AUTHENTICATION",
      "status": "APPROVED",
      "reason": "PLATFORM_AUTHENTICATION_SUCCESSFUL",
      "description": "Request was authenticated successfully."
    },
    {
      "name": "ACCOUNT_ID",
      "status": "APPROVED",
      "reason": "ACCOUNT_ID_PERMITTED",
      "description": "Account ID is permitted.",
      "additional_data": {
        "document_number": "60XXXXXXXXX19",
        "external_id": "",
        "name": "Marcelito"
      }
    },
    {
      "name": "PROCESSING_CODE",
      "status": "APPROVED",
      "reason": "PROCESSING_CODE_FOUND",
      "description": "Processing code was found."
    },
    {
      "name": "PROCESSING_CODE_TYPE",
      "status": "APPROVED",
      "reason": "PROCESSING_CODE_TYPE_VALID",
      "description": "Processing code has a valid balance impact type."
    },
    {
      "name": "ACCOUNT_LIMITS",
      "status": "APPROVED",
      "reason": "ACCOUNT_LIMITS_FOUND",
      "description": "Account limits were found.",
      "additional_data": {
        "available_credit_limit": 746847632710983.1,
        "available_savings_account_limit": 93477.42,
        "available_total_installment_credit": -226,
        "available_withdrawal_credit": -175,
        "total_credit_limit": 1000,
        "total_installment_credit_limit": 200,
        "withdrawal_credit_limit": 300
      }
    },
    {
      "name": "ACCOUNT_STATUS",
      "status": "APPROVED",
      "reason": "ACCOUNT_STATUS_PERMITTED",
      "description": "Account status is permitted."
    },
    {
      "name": "PROGRAM",
      "status": "APPROVED",
      "reason": "PROGRAM_FOUND",
      "description": "Program was found.",
      "additional_data": {
        "program_type": "PRE-PAGO"
      }
    },
    {
      "name": "BALANCES_CONFIG",
      "status": "APPROVED",
      "reason": "BALANCES_CONFIG_FOUND",
      "description": "Balances configuration was found.",
      "additional_data": {
        "amount": "contract_amount",
        "amount_consider": "principal_amount",
        "consider": [
          "AvailableCreditLimit",
          "OverLimit"
        ],
        "impact": [
          "AvailableCreditLimit"
        ],
        "reset_limit": "last_installment"
      }
    },
    {
      "name": "CURRENCY",
      "status": "APPROVED",
      "reason": "CURRENCY_FOUND",
      "description": "Currency was found.",
      "additional_data": {
        "code": "BRL",
        "numeric_code": "986"
      }
    },
    {
      "name": "RATES",
      "status": "APPROVED",
      "reason": "RATES_APPROVED",
      "description": "Rates calculation was performed.",
      "additional_data": {
        "conversion": {
          "conversion_rate": 0,
          "destination": "986",
          "exchange_rate": 1,
          "origin": "986",
          "spread": 0
        }
      }
    },
    {
      "name": "FLEX_CONTROLS",
      "status": "APPROVED",
      "reason": "FLEX_CONTROLS_APPROVED",
      "description": "Authorization passed flex control evaluation.",
      "additional_data": {
        "dry_run": false,
        "evaluated_controls": [
          {
            "id": "bb975c75-ae31-48e8-ac0b-57c677fdd0e4",
            "name": "Purchase 1 Month credit card",
            "evaluation_result": true,
            "deny_code": "MAX_VALUE_P1M",
            "response_code": "63",
            "max_limit": 200000,
            "accumulated_limit": 135127,
            "available_limit": 64873
          }
        ]
      }
    },
    {
      "name": "LEDGER",
      "status": "APPROVED",
      "reason": "LEDGER_APPROVED",
      "description": "Ledger was impacted successfully.",
      "additional_data": {
        "dry_run": false,
        "validation_results": null,
        "account_id": 9999,
        "available_amounts": {
          "validation_status": "APPROVED",
          "details": {
            "result": {
              "available_credit_limit": 746847527710892.1,
              "available_installment_limit": -226,
              "available_savings_account_limit": 93477.42,
              "available_withdraw_limit": -175,
              "held_funds": 91.25,
              "additional_funds": 0,
              "overlimit": 2000000,
              "total_overdraft_limit": 0
            }
          }
        }
      },
      "ledger_operation_status": {
        "validation_status": "APPROVED"
      }
    },
    {
      "name": "AUTHORIZATION",
      "status": "APPROVED",
      "reason": "AUTHORIZATION_CREATED",
      "description": "Authorization was created successfully."
    }
  ]
}