Sign in

v1

latestOpenAPI 3.1.0Copyright Pismo2026-07-247702,7523.1 MB
Payment methods

Request authorization

Use this endpoint to request a new authorization, cancel an existing authorization, or confirm an existing authorization.

With this endpoint, you can 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 guide for additional information.

This endpoint generates Platform authorization created and Payment methods authorization created events.

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

post/payment-methods/v1/authorization

Request body

amountnumber

Total amount of the authorization being requested in the local currency of the acquirer or source location of the transaction.

REQUIRED in authorization requests, and optional in cancellation and confirmation requests. If this amount is omitted, the platform confirms or cancels the same amount as the original authorization. If the original authorization is not available and a forced confirmation is requested, this field is also required.

currency_codestring required

ISO-4217 alphabetic or numeric (3 characters) authorization currency code. For example, either BRL or 986 for Brazilian real.

mti'0100' | '0120' | '0200' | '0202' | '0400' | '0402' | '0420' required

Message type identifier. Indicates if this is an authorization, cancellation, or confirmation request.

  • 0100 - authorization request
  • 0120 - authorization advice request (coming soon)
  • 0200 - authorization SMS request
  • 0202 - confirmation request
  • 0400 - cancellation request
  • 0402 - confirmation of cancellation
  • 0420 - cancellation advice request (coming soon)
networkstring required

Network originating this request.

account_idinteger

Pismo ID of the account to be used as the owner of this request.

REQUIRED if document_number, card information (card.pan or card.stored_id), bank information (bank.account and bank.branch) are not provided.

authorization_codestring

Alphanumeric code generated in an authorization request and assigned to the authorization response.

authorization_datetimestring date-time

Date and time when the authorization request took place outside the Pismo platform, formatted in UTC-0 RFC3339 with milliseconds (yyyy-MM-ddThh:mm:ss.SSSZ).

authorization_mode'CREDIT' | 'DEBIT'

Defines the mode of the authorization being requested. Credit cards can operate only in CREDIT mode while debit cards (from savings or checking accounts) can operate only in DEBIT code. Combo and multi-application cards can operate in both modes.

REQUIRED for card authorization requests (idenfified by card.pan or card.stored_id) with the mti values 0100 and 0120.

beneficiary_idstring

Unique string identifier for the beneficiary associated with the account.

clearing_type'ONLINE' | 'OFFLINE'

Defines whether confirmation is performed at request time (ONLINE) or pending a confirmation request (OFFLINE). If not provided, the platform uses the mti value to define this behavior (0100 for OFFLINE and 0200 for ONLINE).

document_numberstring

Document number related to the account owner of this request. Used in the requests authorized based on client document number.

REQUIRED if account_id, card information (card.pan or card.stored_id), or bank information (bank.account and bank.branch) are not provided.

descriptionstring

Optional text that describes the operation and appears on the customer's statement as a descriptive line for the transaction. If provided, this value populates the soft_descriptor field of the resulting transactions. If not provided, the soft_descriptor field for the transaction inherits its value from the transaction type’s description field.

entry_modestring

Defines the authorization entry mode (two first characters) and pin entry capability (third character). This field should have either two or three digits depending on the usage of the information.

REQUIRED for authorization requests with the mti values 0100, 0120 and 0200.

has_errorboolean

This flag must be used only in the confirmation flow (mti - 0202). If set to true, this indicates that the confirmation operation has an error and the platform will cancel any approved authorization related to this request instead of confirming it.

installment_plan_idstring

ID of the installment plan that should be used to calculate this purchase.

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.

nsustring

Sequential unique number that identifies this authorization.

number_of_installmentsinteger

Number of installments in this authorization request. Purchases without installments should have the value 1.

original_authorization_idinteger

This field can be used to match the original authorization in cancellation and confirmation requests. This should contain the same value received in the authorization_id field for the authorization response.

REQUIRED for cancellation and confirmation requests with the mti values 0400, 0420, 0402 and 0202 if the original_tracking_id is not provided. NOT REQUIRED for confirmation requests when the force original authorization configuration is enabled.

original_tracking_idstring

This field can be used to match the original authorization in cancellation and confirmation requests. This should contain the same value received in the tracking_id field for the authorization response.

REQUIRED for cancellation and confirmation requests with the mti values 0400, 0420, 0402 and 0202 if the original_authorization_id is not provided. NOT REQUIRED for confirmation requests when the force original authorization configuration is enabled.

posting_datestring date

Date of the statement when the authorization will be posted. For authorization with installments, this is where the first installment will be posted being followed by the other installments on next statements. This field will be ignored if a statement_id is provided. If there is an external calculation call, the response of that calculation will take precedence over this field.

pre_authorizationboolean

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

processing_codestring

Unique alphanumeric identifier that defines how the Pismo platform handles this financial authorization.

Required when:

  • mti is 0100, 0120, or 0200
  • mti is 0202 or 0402 and force original authorization configuration is enabled
program_idinteger

This field is used for authorizations that are based on a document number. If this field is provided, the platform uses it to determine which account to use for the authorization with the same program_id or decline if there is no account in this program. If this field is not provided, the platform selects the account based on the configurations.

statement_idinteger

Pismo internal ID of the statement when the authorization will be posted. For authorization with installments, this is where the first installment will be posted being followed by the other installments on next statements. This field takes precedence over the posting_date when both are present. If there is an external calculation call, the response of that calculation takes precendence over this field.

tidstring

Transaction ID received with the authorization message.

tracking_idstring

Unique tracking ID used to identify the authorization request. If not provided, the platform generates a new one and the request is handled as a new request. Different requests using the same tracking ID are considered to be the same request and return the same result.

validation_rulesValidationRules

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

  • LEDGER
  • ACCOUNT_STATUS
  • FLEX_CONTROLS
  • RATES<br>

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

Example request

{
  "amount": 100,
  "currency_code": "986",
  "network": "Mastercard",
  "account_id": 123,
  "authentication": {
    "method": "otp",
    "parameters": {
      "device_id": "abc",
      "token": "123456",
      "user_id": "123456789"
    }
  },
  "authorization_code": "ABC123",
  "authorization_datetime": "2023-01-01T00:00:00.000Z",
  "bank": {
    "account": "2146125",
    "branch": "15235"
  },
  "beneficiary_id": "2c298321-bc21-4039-9c45-780cc6d4ec46",
  "calculated_amounts": {
    "contract_amount": 110,
    "description": "0+24 with interest",
    "fees": [
      {
        "type": "fixed",
        "amount": 10,
        "rate": 10
      }
    ],
    "interests": [
      {
        "type": "monthly",
        "amount": 8.73,
        "rate": 9.99
      }
    ],
    "installments": [
      {
        "number": 1,
        "contract_amount": 11,
        "principal_amount": 10,
        "amortization_amount": 7.5,
        "fees": [
          {
            "type": "fixed",
            "amount": 10,
            "rate": 10
          }
        ],
        "interests": [
          {
            "type": "monthly",
            "amount": 8.73,
            "rate": 9.99
          }
        ],
        "taxes": {
          "currency": "BRL"
        }
      }
    ],
    "number_of_installments": 12,
    "plan_id": "PLAN_ID_1",
    "principal_amount": 100,
    "taxes": {
      "currency": "BRL"
    },
    "total_annual_rate": 27,
    "total_monthly_rate": 9.99,
    "additional_financial_details": {
      "effective_annual_cost": 0.13,
      "effective_monthly_cost": 0.13,
      "annual_interest_rate": 10
    }
  },
  "card": {
    "pan": "5555550000000001",
    "stored_id": "652973000071210932",
    "expiration_date": "2601",
    "cvv2": "123",
    "track1_data": "123"
  },
  "document_number": "39947739977",
  "description": "Custom purchase.",
  "entry_mode": "051 # 05 - Chip / 1 - Pin supported",
  "has_error": true,
  "installment_plan_id": "PLAN_0_24",
  "merchant": {
    "id": "12399",
    "category_code": "5099",
    "name": "Acme",
    "city": "San Diego",
    "country": "USA",
    "terminal_id": "12345699",
    "marketplace_id": "mk123456"
  },
  "metadata": "{ \"key\": \"value\"}",
  "nsu": "12789223",
  "number_of_installments": 12,
  "original_authorization_id": 58799254,
  "original_tracking_id": "ab879e9e-433b-499f-a77b-4e90ab509afd",
  "posting_date": "2023-01-01T00:00:00.000Z",
  "processing_code": "00AB01",
  "program_id": 123,
  "statement_id": 1234455,
  "tid": "10119031908214800419",
  "tracking_id": "ab879e9e-433b-499f-a77b-4e90ab509afd",
  "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"
    }
  }
}

Response

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

account_idinteger required

Pismo ID of the account assigned as the owner of this request.

authorization_codestring required

Alphanumeric code generated in an authorization request and assigned to the authorization response. Used on cancellation or confirmation requests to match the original authorization.

authorization_idinteger required

Pismo ID of the authorization created for this request.

number_of_installmentsinteger required

Number of installments in this authorization request. Purchases without installments should have the value 1.

response_codestring required

Response code indicating the decision for the authorization request. Refer to Authorization validation rules for platform operations for details.

tracking_idstring required

Tracking ID used to identify the authorization request.

custom_messagestring

Message customized to describe the authorization response.

denial_codestring

Denial code that indicates the reason why the request was denied.

datetime_utcstring date-time

Date and time when the authorization is created inside the Pismo platform in the UTC 0 time zone.

Example response

{
  "authorization_id": 123,
  "tracking_id": "auth-9944",
  "account_id": 8899,
  "authorization_code": "MQ94GG",
  "response_code": "00",
  "denial_code": "",
  "custom_message": "",
  "datetime_utc": "2025-07-15T05:50:47.049Z",
  "number_of_installments": 2,
  "calculated_amounts": {
    "contract_amount": 10510,
    "principal_amount": 10000,
    "installment_amount": 5255,
    "additional_financial_details": {},
    "postings": {
      "fixed_amount": 10,
      "percentage_amount": 500
    },
    "rates": {
      "conversion_rate": 1
    },
    "installments": [
      {
        "number": 1,
        "installment_amount": 5255,
        "principal_amount": 5000
      },
      {
        "number": 2,
        "installment_amount": 5255,
        "principal_amount": 5000
      }
    ]
  },
  "validation_results": [
    {
      "name": "CARD",
      "status": "APPROVED",
      "reason": "CARD_FOUND",
      "description": "Card was found.",
      "additional_data": {
        "card_hash": "9XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX="
      }
    },
    {
      "name": "CARD_AUTHORIZATION_MODE",
      "status": "APPROVED",
      "reason": "CARD_AUTHORIZATION_MODE_VALID",
      "description": "Card has authorization mode enabled.",
      "additional_data": {
        "authorization_mode": "CREDIT"
      }
    },
    {
      "name": "BANK_ACCOUNT",
      "status": "APPROVED",
      "reason": "BANK_ACCOUNT_FOUND",
      "description": "Bank account was found.",
      "additional_data": {
        "account_id": 99999
      }
    },
    {
      "name": "ACCOUNT",
      "status": "APPROVED",
      "reason": "ACCOUNT_FOUND",
      "description": "Account was found.",
      "additional_data": {
        "account_id": 2417
      }
    },
    {
      "name": "DOCUMENT_NUMBER",
      "status": "APPROVED",
      "reason": "DOCUMENT_NUMBER_FOUND",
      "description": "Account was found successfully based on document number.",
      "additional_data": {
        "document_number_present": true
      }
    },
    {
      "name": "PROCESSING_CODE_MAPPER",
      "status": "APPROVED",
      "reason": "PROCESSING_CODE_MAPPED",
      "description": "Processing code was mapped successfully.",
      "additional_data": {
        "mapped_processing_code": "2XXXX0",
        "original_processing_code": "2XXXX0"
      }
    },
    {
      "name": "ACCEPTANCE",
      "status": "SKIPPED",
      "reason": "ACCEPTANCE_SKIPPED",
      "description": "Payment methods acceptances validation was skipped.",
      "additional_data": {
        "cause": "Payment methods authorization acceptance was not found for this request."
      }
    },
    {
      "name": "CONFIG",
      "status": "APPROVED",
      "reason": "CONFIG_FOUND",
      "description": "Payment methods configuration was found."
    },
    {
      "name": "PLATFORM_AUTHENTICATION",
      "status": "APPROVED",
      "reason": "PLATFORM_AUTHENTICATION_SUCCESSFUL",
      "description": "Request was authenticated successfully."
    },
    {
      "name": "PROGRAM_PARAMETER",
      "status": "SKIPPED",
      "reason": "PROGRAM_PARAMETER_SKIPPED",
      "description": "Program parameters validation was skipped.",
      "additional_data": {
        "cause": "Authorization is not performed using a card.",
        "program_id": 177
      }
    },
    {
      "name": "MERCHANT",
      "status": "SKIPPED",
      "reason": "MERCHANT_SKIPPED",
      "description": "Merchant validation was skipped.",
      "additional_data": {
        "cause": "This rule is disabled on configurations.",
        "marketplace_id": "",
        "merchant_external_id": ""
      }
    },
    {
      "name": "CARD_ARQC",
      "status": "SKIPPED",
      "reason": "CARD_ARQC_SKIPPED",
      "description": "ARQC validation was skipped.",
      "additional_data": {
        "arqc_presence": false,
        "cause": "Authorization is not performed using a card."
      }
    },
    {
      "name": "CARD_PIN",
      "status": "SKIPPED",
      "reason": "CARD_PIN_SKIPPED",
      "description": "PIN validation was skipped.",
      "additional_data": {
        "pin_presence": false,
        "cause": "Authorization is not performed using a card."
      }
    },
    {
      "name": "CARD_CVV",
      "status": "SKIPPED",
      "reason": "CARD_CVV_SKIPPED",
      "description": "CVV validation was skipped.",
      "additional_data": {
        "track1_presence": false,
        "track2_presence": false,
        "cause": "Authorization is not performed using a card.",
        "code": ""
      }
    },
    {
      "name": "CARD_CVV2",
      "status": "SKIPPED",
      "reason": "CARD_CVV2_SKIPPED",
      "description": "CVV2 validation was skipped.",
      "additional_data": {
        "cvv2_presence": false,
        "entered_expiration_date": "2806",
        "cause": "Authorization is not performed using a card.",
        "code": ""
      }
    },
    {
      "name": "CARD_STATUS",
      "status": "APPROVED",
      "reason": "CARD_STATUS_VALID",
      "description": "Card is in valid status.",
      "additional_data": {
        "card_status": "NORMAL"
      }
    },
    {
      "name": "CARD_ENTERED_EXPIRATION_DATE",
      "status": "APPROVED",
      "reason": "CARD_ENTERED_EXPIRATION_DATE_VALID",
      "description": "Entered expiration date matches card expiration date.",
      "additional_data": {
        "card_expiration_date": "2806",
        "entered_expiration_date": "2806"
      }
    },
    {
      "name": "CARD_EXPIRATION_DATE",
      "status": "APPROVED",
      "reason": "CARD_NOT_EXPIRED",
      "description": "Card is not expired.",
      "additional_data": {
        "card_expiration_date": "2806"
      }
    },
    {
      "name": "CARD_PASSWORD_TRIES",
      "status": "APPROVED",
      "reason": "CARD_PASSWORD_TRIES_ALLOWED",
      "description": "Password tries are within configured threshold.",
      "additional_data": {
        "current_password_tries": 0,
        "password_tries_allowed": 3
      }
    },
    {
      "name": "CARD_ATC",
      "status": "APPROVED",
      "reason": "CARD_ATC_WITHIN_ALLOWED_RANGE",
      "description": "ATC is within allowed range.",
      "additional_data": {
        "current_atc": "10",
        "previous_atc": "[9,8,7,5,1]",
        "min_offset_parameter": "5",
        "max_offset_parameter": "15"
      }
    },
    {
      "name": "EXTERNAL_CALCULATION",
      "status": "APPROVED",
      "reason": "EXTERNAL_CALCULATION_SUCCESSFUL",
      "description": "External calculation was performed successfully."
    },
    {
      "name": "PAYMENT_METHODS_INTEGRITY",
      "status": "APPROVED",
      "reason": "PAYMENT_METHODS_INTEGRITY_CREATED",
      "description": "Payment methods integrity message was created successfully."
    },
    {
      "name": "ACCOUNT_ID",
      "status": "APPROVED",
      "reason": "ACCOUNT_ID_PERMITTED",
      "description": "Account ID is permitted.",
      "additional_data": {
        "document_number": "6XXXXXXXXXXX9",
        "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": 746847632710901.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": "ANTI_FRAUD",
      "status": "APPROVED",
      "reason": "ANTI_FRAUD_APPROVED",
      "description": "Authorization passed anti-fraud evaluation.",
      "additional_data": {
        "executed_steps": [],
        "force_approve": false,
        "override": false,
        "override_type": "NONE"
      }
    },
    {
      "name": "AUTHORIZATION",
      "status": "APPROVED",
      "reason": "AUTHORIZATION_CREATED",
      "description": "Authorization was created successfully."
    },
    {
      "name": "PAYMENT_METHODS_PERSISTENCE",
      "status": "APPROVED",
      "reason": "PAYMENT_METHODS_PERSISTENCE_CREATED",
      "description": "Payment methods record was created successfully."
    }
  ]
}