--- updatedAt: 2026-05-29T16:44:17.000Z --- Fetch the complete documentation index at: https://developers.pismo.io/pismo-docs/llms.txt. Use this file to discover all available pages before exploring further. # 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](doc:payment-methods) guide for additional information. This endpoint generates [Platform authorization created](https://developers.pismo.io/events/docs/platform-authorization-platform-authorization-1) and [Payment methods authorization created](https://developers.pismo.io/events/docs/payment-methods-authorization-1) events. **Note:** This is a PCI endpoint, use the https://gw-pci.pismolabs.io environment. # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "Core platform - Payment methods", "version": "1.0.0", "description": "API to handle payments.", "contact": { "name": "API Support", "url": "https://developers.pismo.io/support/" }, "license": { "name": "Copyright Pismo" } }, "servers": [ { "url": "https://sandbox.pismolabs.io", "description": "Sandbox API server for testing" }, { "url": "https://gw-pci.pismolabs.io", "description": "Sandbox PCI API server for testing" } ], "tags": [ { "name": "Payment methods", "description": "Endpoints to manage cash-in and cash-out payments and P2P transfers." } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Account access token. Tokens can expire quickly, which can result in an \"Unauthorized\" error.", "bearerFormat": "JWT" } }, "schemas": { "ValidationRules": { "type": "object", "description": "Validation rules performed in the flow. Each key is a rule name (such as `ACCOUNT_STATUS` or `LEDGER`) and the value is its configuration.", "additionalProperties": { "$ref": "#/components/schemas/RuleConfig" }, "example": { "ACCOUNT_STATUS": { "disable": false, "force": false, "denial_reasons": { "ACCOUNT_STATUS_NOT_PERMITTED": { "response_code": "57", "denial_code": "DAL" } } }, "LEDGER": { "denial_reasons": { "LEDGER_INSUFFICIENT_FUNDS": { "response_code": "51", "denial_code": "DAL" }, "LEDGER_NOT_ALLOWED_OPERATION": { "response_code": "57", "denial_code": "DAL" } } } } }, "RuleConfig": { "type": "object", "description": "Configuration related to a rule.", "properties": { "denial_reasons": { "$ref": "#/components/schemas/DenialReasons" }, "disable": { "type": "boolean", "description": "Flag to disable this rule throughout Payments validation flow." }, "force": { "type": "boolean", "description": "Flag to force this rule throughout Payments validation flow." } } }, "DenialReasons": { "type": "object", "description": "Denial reasons linked to a rule.", "additionalProperties": { "$ref": "#/components/schemas/ReasonConfig" } }, "ReasonConfig": { "type": "object", "properties": { "denial_code": { "type": "string", "description": "Denial code that must be used when this denial reason is the one that caused the request to be denied.", "example": "DAL" }, "response_code": { "type": "string", "description": "Response code that must be used when this denial reason is the one that caused the request to be denied.", "example": "57" } } }, "CalculatedAmountsAuthorization": { "type": "object", "description": "Calculated amounts for the authorization.", "properties": { "contract_amount": { "type": "number", "description": "Total amount of the authorization after calculation and addition of any necessary fees.", "example": 110 }, "description": { "type": "string", "description": "Description of the plan.", "example": "0+24 with interest" }, "fees": { "$ref": "#/components/schemas/Fee" }, "interests": { "$ref": "#/components/schemas/Interest" }, "installments": { "$ref": "#/components/schemas/InstallmentsAuthorization" }, "number_of_installments": { "type": "integer", "minimum": 2, "maximum": 100, "description": "Number of installments in this calculation.", "example": 12 }, "plan_id": { "type": "string", "description": "ID of the plan used to perform this calculation.", "example": "PLAN_ID_1" }, "principal_amount": { "type": "number", "description": "Total amount of the authorization after calculation without the addition of any fees.", "example": 100 }, "taxes": { "$ref": "#/components/schemas/Tax" }, "total_annual_rate": { "type": "number", "description": "Total interest percentage rate applied to this contract annually.", "minimum": 0, "example": 27 }, "total_monthly_rate": { "type": "number", "description": "Total interest percentage rate applied to this contract monthly.", "minimum": 0, "example": 9.99 }, "additional_financial_details": { "$ref": "#/components/schemas/AdditionalFinancialDetails" } } }, "AdditionalFinancialDetails": { "description": "Additional information related to the authorization.", "properties": { "effective_annual_cost": { "type": "number", "description": "Total annual finance charge expressed as a percentage rate.", "example": 0.13 }, "effective_monthly_cost": { "type": "number", "description": "Total monthly finance charge expressed as a percentage rate.", "example": 0.13 }, "annual_interest_rate": { "type": "number", "description": "Percentage of interest charged over the course of a year.", "example": 10 } } }, "Fee": { "type": "array", "description": "List of applied fees on this calculation.", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Type of applied fee. For example, fixed, percentage, or any other type.", "example": "fixed", "minLength": 2, "maxLength": 30 }, "amount": { "type": "number", "description": "Calculated amount of this fee.", "example": 10 }, "rate": { "type": "number", "description": "When using a percentage fee, this is the percentage rate used for calculating this fee. For example, the value `10` indicates 10%.", "minimum": 0, "example": 10 } } } }, "Interest": { "type": "array", "description": "List of interests applied to this calculation.", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Type of applied interest. For example, weekly, monthly, annually, or any other type.", "example": "monthly", "minLength": 2, "maxLength": 30 }, "amount": { "type": "number", "description": "Calculated amount of this interest.", "example": 8.73 }, "rate": { "type": "number", "description": "Percentage rate used for calculating this interest. For example, the value `9.99` indicates 9.99%.", "minimum": 0, "example": 9.99 } } } }, "Tax": { "type": "array", "description": "List of applied taxes on this calculation.", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "Type of applied tax. For example, DAILY_IOF, FIXED_IOF, INTERNATIONAL_IOF (taxes on financial operations) in Brazil, SDRT (stamp duty reserve tax) in United Kingdom, FTT (financial transaction tax) in European Union, STT (securities transaction tax) in India, or any other type.", "example": "INTERNATIONAL_IOF", "minLength": 2, "maxLength": 50 }, "amount": { "type": "number", "description": "Calculated amount of this tax.", "example": 0.38 }, "rate": { "type": "number", "description": "Percentage rate used for calculating this tax. For example, the value `0.38` indicates 0.38%.", "minimum": 0, "example": 0.38 } } } }, "InstallmentsAuthorization": { "type": "array", "description": "List and details for each installment.", "items": { "type": "object", "properties": { "number": { "type": "integer", "description": "Order number of this installment in the hierarchy.", "minimum": 1, "maximum": 100, "example": 1 }, "contract_amount": { "type": "number", "description": "Total amount of the installment after calculation and addition of any necessary fees.", "example": 11 }, "principal_amount": { "type": "number", "description": "Total amount of the installment after calculation without the addition of any fees.", "example": 10 }, "amortization_amount": { "type": "number", "description": "Amortization amount related to this installment.", "example": 7.5 }, "fees": { "$ref": "#/components/schemas/Fee" }, "interests": { "$ref": "#/components/schemas/Interest" }, "taxes": { "$ref": "#/components/schemas/Tax" } } } }, "PaymentMethodsAuthorizationRequest": { "type": "object", "description": "Request payment methods authorization processing.", "required": [ "currency_code", "mti", "network" ], "properties": { "amount": { "type": "number", "description": "Total amount of the authorization being requested in the local currency of the acquirer or source location of the transaction.\n\n**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.\n", "example": 100 }, "currency_code": { "type": "string", "description": "ISO-4217 alphabetic or numeric (3 characters) authorization currency code. For example, either BRL or 986 for Brazilian real.", "example": "986" }, "mti": { "type": "string", "description": "Message type identifier. Indicates if this is an authorization, cancellation, or confirmation request.\n- `0100` - authorization request\n- `0120` - authorization advice request (coming soon)\n- `0200` - authorization SMS request\n- `0202` - confirmation request\n- `0400` - cancellation request\n- `0402` - confirmation of cancellation\n- `0420` - cancellation advice request (coming soon)\n", "enum": [ "0100", "0120", "0200", "0202", "0400", "0402", "0420" ] }, "network": { "type": "string", "description": "Network originating this request.", "example": "Mastercard" }, "account_id": { "type": "integer", "description": "Pismo ID of the account to be used as the owner of this request. \n\n**REQUIRED** if `document_number`, card information (`card.pan` or `card.stored_id`), bank information (`bank.account` and `bank.branch`) are not provided.\n", "example": 123 }, "authentication": { "$ref": "#/components/schemas/Authentication" }, "authorization_code": { "type": "string", "description": "Alphanumeric code generated in an authorization request and assigned to the authorization response.", "example": "ABC123" }, "authorization_datetime": { "type": "string", "format": "date-time", "description": "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).", "example": "2023-01-01T00:00:00.000Z" }, "authorization_mode": { "type": "string", "description": "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. \n\n**REQUIRED** for card authorization requests (idenfified by `card.pan` or `card.stored_id`) with the `mti` values `0100` and `0120`.\n", "enum": [ "CREDIT", "DEBIT" ] }, "bank": { "type": "object", "description": "Identifies bank's information. If provided, both bank `account` and `branch` fields are **REQUIRED**.", "properties": { "account": { "type": "string", "description": "Identifies the bank's account. This field should be used in the requests authorized based on the client's bank. \n\n**REQUIRED** together with the `bank.branch` field if `account_id`, `document_number`, or card information (`card.pan` or `card.stored_id`) are not provided.\n", "example": "2146125" }, "branch": { "type": "string", "description": "Identifies the bank's branch. This field should be used in requests authorized based on the client's bank. \n\n**REQUIRED** together with the `bank.account` field if `account_id`, `document_number`, or card information (`card.pan` or `card.stored_id`) are not provided.\n", "example": "15235" } } }, "beneficiary_id": { "type": "string", "description": "Unique string identifier for the beneficiary associated with the account.", "example": "2c298321-bc21-4039-9c45-780cc6d4ec46" }, "calculated_amounts": { "$ref": "#/components/schemas/CalculatedAmountsAuthorization" }, "card": { "type": "object", "description": "Contains all information related to the card used to perform this authorization. \n\n**REQUIRED** if `account_id`, `document_number`, or bank information (`bank.account` and `bank.branch`) are not provided.\n", "properties": { "pan": { "type": "string", "description": "Primary account number of the card being used for authorization. Either this field or `stored_id` is **REQUIRED** to identify the card to be used in the authorization process.", "example": "5555550000000001" }, "stored_id": { "type": "string", "description": "ID of the card-on-file stored in the platform. Either this field or `pan` is **REQUIRED** to identify the card to be used in the authorization process.", "example": "652973000071210932" }, "expiration_date": { "type": "string", "description": "Card expiration date in the YYMM format entered by the cardholder at the authorization request.", "example": "2601" }, "cvv2": { "type": "string", "description": "CVV2 entered by the cardholder at the authorization request.", "example": "123" }, "track1_data": { "type": "string", "description": "Track1 data captured at the terminal while performing an authorization with magnet stripe.", "example": "123" }, "track2_data": { "type": "string", "description": "Track2 data captured at the terminal while performing an authorization with magnet stripe." }, "pin_block": { "type": "string", "description": "Pin block related to the password entered by the cardholder at the authorization request." }, "cryptogram_data": { "type": "object", "description": "Cryptogram data captured at the terminal while performing an authorization using chip.", "properties": { "amount_authorized": { "type": "string", "description": "Amount authorized referring to the tag 9F02." }, "application_cryptogram": { "type": "string", "description": "Application cryptogram information referring to the tag 9F26." }, "application_interchange_profile": { "type": "string", "description": "Application interchange profile referring to the tag 82." }, "application_transaction_counter": { "type": "string", "description": "Application transaction counter referring to the tag 9F36." }, "application_version_number": { "type": "string", "description": "Application version number referring to the tag 9F09." }, "cardholder_verification_method": { "type": "string", "description": "Cardholder verification method (CVM) results referring to the tag 9F34." }, "cryptogram_information_data": { "type": "string", "description": "Cryptogram information data referring to the tag 9F27." }, "dedicated_file_name": { "type": "string", "description": "Dedicated file name referring to the tag 84." }, "interface_device_serial_number": { "type": "string", "description": "Interface device serial number referring to the tag 9F1E." }, "issuer_application_data": { "type": "string", "description": "Issuer application data referring to the tag 9F10." }, "issuer_authentication_data": { "type": "string", "description": "Issuer authentication data referring to the tag 91." }, "issuer_script_template": { "type": "string", "description": "Issuer script template referring to the tag 71." }, "pan_sequence_number": { "type": "string", "description": "Pan sequence number referring to the tag 5F34." }, "terminal_capabilities": { "type": "string", "description": "Terminal capabilities information referring to the tag 9F33." }, "terminal_country_code": { "type": "string", "description": "Application interchange profile referring to the tag 9F1A." }, "terminal_type": { "type": "string", "description": "Terminal type referring to the tag 9F35." }, "terminal_verification_result": { "type": "string", "description": "Terminal verification result (TVR) referring to the tag 95." }, "transaction_category_code": { "type": "string", "description": "Transaction category code referring to the tag 9F53." }, "transaction_currency_code": { "type": "string", "description": "Transaction currency code referring to the tag 5F2A." }, "transaction_date": { "type": "string", "description": "Transaction date referring to the tag 9A." }, "transaction_sequence_counter": { "type": "string", "description": "Transaction sequence counter referring to the tag 9F41." }, "transaction_type": { "type": "string", "description": "Transaction type referring to the tag 9C." }, "unpredictable_number": { "type": "string", "description": "Unpredictable number referring to the tag 9F37." } } } } }, "clearing_type": { "type": "string", "description": "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`).", "enum": [ "ONLINE", "OFFLINE" ] }, "document_number": { "type": "string", "description": "Document number related to the account owner of this request. Used in the requests authorized based on client document number. \n\n**REQUIRED** if `account_id`, card information (`card.pan` or `card.stored_id`), or bank information (`bank.account` and `bank.branch`) are not provided.\n", "example": "39947739977" }, "description": { "type": "string", "description": "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.", "example": "Custom purchase." }, "entry_mode": { "type": "string", "description": "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. \n\n**REQUIRED** for authorization requests with the `mti` values `0100`, `0120` and `0200`.\n", "example": "051 # 05 - Chip / 1 - Pin supported" }, "has_error": { "type": "boolean", "description": "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.", "example": true, "default": false }, "installment_plan_id": { "type": "string", "description": "ID of the installment plan that should be used to calculate this purchase.", "example": "PLAN_0_24" }, "merchant": { "type": "object", "description": "All information related to the merchant where the authorization took place. \n\nOnly used for authorization requests with the `mti` values `0100` and `0120`.\n", "properties": { "id": { "type": "string", "description": "Identifies the card acceptor that defines the point of the transaction in both local and interchange environments. This is used as a merchant ID to uniquely identify the merchant in a POS transaction.\n\n**REQUIRED** if the `merchant` object is filled in.\n", "example": "12399" }, "category_code": { "type": "string", "description": "Merchant category code (MCC) of the merchant’s type of business or service. \n\n**REQUIRED** if the `merchant` object is filled in.\n", "example": "5099" }, "name": { "type": "string", "description": "Name of the merchant where the authorization is performed. \n\n**REQUIRED** if the `merchant` object is filled in.\n", "example": "Acme" }, "city": { "type": "string", "description": "City of the merchant where the authorization is performed.", "example": "San Diego" }, "country": { "type": "string", "description": "Country code of the merchant where the authorization is performed. \n\n**REQUIRED** if the `merchant` object is filled in.\n", "example": "USA" }, "terminal_id": { "type": "string", "description": "ID of the terminal at the card acceptor location.", "example": "12345699" }, "marketplace_id": { "type": "string", "description": "ID of the marketplace where this purchase took place.\n\n**REQUIRED** if the `merchant` object is filled in.\n", "example": "mk123456" } } }, "metadata": { "$ref": "#/components/schemas/Metadata" }, "nsu": { "type": "string", "description": "Sequential unique number that identifies this authorization.", "example": "12789223" }, "number_of_installments": { "type": "integer", "minimum": 1, "maximum": 100, "description": "Number of installments in this authorization request. Purchases without installments should have the value 1.", "example": 12 }, "original_authorization_id": { "type": "integer", "description": "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. \n\n**REQUIRED** for cancellation and confirmation requests with the `mti` values `0400`, `0420`, `0402` and `0202` if the `original_tracking_id` is not provided.\n**NOT REQUIRED** for confirmation requests when the force original authorization configuration is enabled.\n", "example": 58799254 }, "original_tracking_id": { "type": "string", "description": "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. \n\n**REQUIRED** for cancellation and confirmation requests with the `mti` values `0400`, `0420`, `0402` and `0202` if the `original_authorization_id` is not provided.\n**NOT REQUIRED** for confirmation requests when the force original authorization configuration is enabled.\n", "example": "ab879e9e-433b-499f-a77b-4e90ab509afd" }, "posting_date": { "type": "string", "format": "date", "description": "Date of the statement when the authorization will be posted. \nFor authorization with installments, this is where the first installment will be posted being followed by the other installments on next statements.\nThis field will be ignored if a `statement_id` is provided.\nIf there is an external calculation call, the response of that calculation will take precedence over this field.\n", "example": "2023-01-01T00:00:00.000Z" }, "pre_authorization": { "$ref": "#/components/schemas/PreAuthorization" }, "processing_code": { "type": "string", "description": "Unique alphanumeric identifier that defines how the Pismo platform handles this financial authorization. \n\n**Required when:** \n - `mti` is `0100`, `0120`, or `0200`\n - `mti` is `0202` or `0402` and force original authorization configuration is enabled\n", "example": "00AB01" }, "program_id": { "type": "integer", "description": "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.\n", "example": 123 }, "statement_id": { "type": "integer", "description": "Pismo internal ID of the statement when the authorization will be posted. \nFor authorization with installments, this is where the first installment will be posted being followed by the other installments on next statements.\nThis field takes precedence over the `posting_date` when both are present.\nIf there is an external calculation call, the response of that calculation takes precendence over this field.\n", "example": 1234455 }, "tid": { "type": "string", "description": "Transaction ID received with the authorization message.", "example": "10119031908214800419" }, "tracking_id": { "type": "string", "description": "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.", "example": "ab879e9e-433b-499f-a77b-4e90ab509afd" }, "validation_rules": { "$ref": "#/components/schemas/ValidationRules" }, "authorization_validations": { "$ref": "#/components/schemas/AuthorizationValidations" } } }, "PaymentMethodsAuthorizationResponse": { "type": "object", "description": "Payment methods authorization response.", "required": [ "account_id", "authorization_code", "authorization_id", "calculated_amounts", "number_of_installments", "response_code", "tracking_id", "validation_results" ], "properties": { "account_id": { "type": "integer", "description": "Pismo ID of the account assigned as the owner of this request.", "example": 123 }, "authorization_code": { "type": "string", "description": "Alphanumeric code generated in an authorization request and assigned to the authorization response. Used on cancellation or confirmation requests to match the original authorization.", "example": "ABC123" }, "authorization_id": { "type": "integer", "description": "Pismo ID of the authorization created for this request." }, "calculated_amounts": { "type": "object", "properties": { "contract_amount": { "type": "number", "description": "Total amount of the authorization after calculation with the addition of any necessary fees.", "example": 100 }, "principal_amount": { "type": "number", "description": "Total amount of the authorization after calculation without the addition of any necessary fees.", "example": 100 }, "postings": { "type": "object", "description": "Information about the applied fee or tax.", "additionalProperties": { "type": "number", "description": "Value of the applied fee or tax." } }, "rates": { "type": "object", "description": "Rates used to calculate fees and taxes represented on Postings object.", "additionalProperties": { "type": "number", "description": "Value of the applied rate." } } } }, "number_of_installments": { "type": "integer", "description": "Number of installments in this authorization request. Purchases without installments should have the value `1`.", "example": 12 }, "response_code": { "type": "string", "description": "Response code indicating the decision for the authorization request. Refer to [Authorization validation rules for platform operations](https://developers.pismo.io/pismo-docs/docs/authorization-validation-rules-for-platform-operations) for details.", "example": "00" }, "tracking_id": { "type": "string", "description": "Tracking ID used to identify the authorization request.", "example": "ab879e9e-433b-499f-a77b-4e90ab509afd" }, "validation_results": { "$ref": "#/components/schemas/ValidationResults" }, "custom_message": { "type": "string", "description": "Message customized to describe the authorization response.", "example": "Custom message" }, "denial_code": { "type": "string", "description": "Denial code that indicates the reason why the request was denied.", "example": "ABC" }, "datetime_utc": { "format": "date-time", "description": "Date and time when the authorization is created inside the Pismo platform in the UTC 0 time zone.", "type": "string", "example": "2023-01-01T00:00:00.000Z" } }, "example": { "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." } ] } }, "NewErrorModel": { "description": "API generic returned error.", "type": "object", "properties": { "code": { "type": "string", "description": "Error code." }, "message": { "type": "string", "description": "Error description." }, "details": { "type": "string", "description": "Additional error details." } }, "title": "NewErrorModel" }, "ErrorsResponse": { "type": "array", "items": { "$ref": "#/components/schemas/NewErrorModel" } }, "Metadata": { "type": "object", "description": "This optional user-defined key-value object field can be used with external operations to provide additional context or supplementary custom information for the operation. \n\nThe Pismo platform does not perform any validation or processing on this field but passes this object to the acquirer in transactions involving calls to the acquirer and sends it in the events related to the stream of data produced at the end of the request.\n\n**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](https://developers.pismo.io/pismo-docs/reference/get-started-with-pismo-apis#metadata).\n", "example": { "any-key": "any-value" } }, "ValidationResults": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Name of the evaluated rule.", "example": "LEDGER" }, "status": { "type": "string", "enum": [ "APPROVED", "REJECTED", "SKIPPED" ], "description": "Identifies if the rule was approved, rejected, or skipped during the validation flow.", "example": "REJECTED" }, "reason": { "type": "string", "description": "Status reason why the specific rule was approved, rejected, or skipped.", "example": "LEDGER_INSUFFICIENT_FUNDS" }, "description": { "type": "string", "description": "Description of the validation result.", "example": "The authorization amount is greater than the account available limit." }, "additional_data": { "description": "Additional data for the validation result. This varies from validation to validation, but every denied validation has the `denial_code` and `response_code` fields.", "type": "object" } } } }, "PreAuthorization": { "type": "boolean", "description": "If set to `true`, this flag indicates that the operation is pre-authorized and requires additional confirmation.", "default": false, "example": false }, "AuthorizationValidations": { "type": "object", "description": "Contains additional data to be used in the authorization flow. This field is only considered for authorizations. Cancellations and confirmations will retrieve it based on the original authorization.", "properties": { "is_device_registered": { "description": "Indicates whether the device used for the operation is registered according to the financial institution's security policies.", "type": "boolean", "example": true }, "associated_ids": { "$ref": "#/components/schemas/AssociatedIDs" } } }, "AssociatedIDs": { "type": "object", "description": "External IDs used in the authorization flow.", "properties": { "payment_id": { "description": "External ID associated with the authorization.", "type": "string", "example": "319d00f5-48de-4c71-ad47-40b1e9c4e37f" }, "origin_id": { "description": "External ID of the origin of the authorization.", "type": "string", "example": "CUSTOM_ORIGIN" } } }, "Authentication": { "type": "object", "description": "Authentication object.", "properties": { "method": { "type": "string", "description": "Authentication method. \n- `otp` is when the operation needs to be authenticated.\n- `transaction_signing` is when the operation has been authenticated already but needs to be validated.\n", "example": "otp" }, "parameters": { "type": "object", "description": "Authentication parameters will vary, depending on type of the method used.", "properties": { "device_id": { "type": "string", "description": "Device ID. Used in the `otp` authentication method.", "example": "abc" }, "token": { "type": "string", "description": "Authentication token. Used in the `otp` authentication method.", "example": "123456" }, "user_id": { "type": "string", "description": "User ID. Used in the `otp` authentication method.", "example": "123456789" }, "hash": { "type": "string", "description": "Value generated at the time of authentication via OTP and intended for authentication via signing. Used in the `transaction_signing` authentication method." }, "signing_data": { "type": "object", "description": "Object that contains authorization information provided at time of signing. Used in the `transaction_signing` authentication method." } } } } } }, "responses": { "401Unauthorized": { "description": "Access token is missing or invalid." }, "403Forbidden": { "description": "The request has been lost." } } }, "security": [ { "BearerAuth": [] } ], "paths": { "/payment-methods/v1/authorization": { "post": { "summary": "Request authorization", "description": "Use this endpoint to request a new authorization, cancel an existing authorization, or confirm an existing authorization.\n\nWith 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.\n\nRefer to the [Payment methods](https://developers.pismo.io/pismo-docs/docs/payment-methods) guide for additional information.\n\nThis endpoint generates [Platform authorization created](https://developers.pismo.io/events/docs/platform-authorization-platform-authorization-1) and [Payment methods authorization created](https://developers.pismo.io/events/docs/payment-methods-authorization-1) events.\n\n**Note:** This is a PCI endpoint, use the https://gw-pci.pismolabs.io environment.\n", "operationId": "post-authorization", "tags": [ "Payment methods" ], "requestBody": { "description": "Request authorization processing body.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMethodsAuthorizationRequest" } } } }, "responses": { "200": { "description": "Authorization was processed successfully, existing authorization with the corresponding `tracking_id` returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMethodsAuthorizationResponse" } } } }, "201": { "description": "Authorization request was processed successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMethodsAuthorizationResponse" }, "examples": { "Create authorization request": { "value": { "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": "APPROVED", "reason": "ACCEPTANCE_FOUND", "description": "Payment methods acceptances were found." }, { "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": "APPROVED", "reason": "PROGRAM_PARAMETER_FOUND", "description": "Program parameters were found successfully.", "additional_data": { "program_id": 99 } }, { "name": "MERCHANT", "status": "APPROVED", "reason": "MERCHANT_VALID_STATUS", "description": "Merchant has valid status.", "additional_data": { "marketplace_id": "FL-123456", "status": "ACTIVE", "merchant_external_id": "102030" } }, { "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." } ] } }, "Confirm authorization request": { "value": { "authorization_id": 2413411561, "tracking_id": "3277a9b7-81cd-403c-852a-d632b47fbcae", "account_id": 2417, "authorization_code": "MMEYFR", "response_code": "00", "denial_code": "", "custom_message": "", "datetime_utc": "2025-07-15T13:34:57.221Z", "number_of_installments": 2, "calculated_amounts": { "contract_amount": 10000, "principal_amount": 10000, "installment_amount": 5000, "additional_financial_details": null, "postings": {}, "rates": { "conversion_rate": 1 }, "installments": [ { "number": 1, "installment_amount": 5000, "principal_amount": 5000, "amortization_amount": 0 }, { "number": 2, "installment_amount": 5000, "principal_amount": 5000, "amortization_amount": 0 } ] }, "validation_results": [ { "name": "CARD", "status": "APPROVED", "reason": "CARD_FOUND", "description": "Card was found successfully.", "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": 9999 } }, { "name": "ACCOUNT", "status": "APPROVED", "reason": "ACCOUNT_FOUND", "description": "Account was found.", "additional_data": { "account_id": 2417 } }, { "name": "AUTHORIZATION_RETRIEVAL", "status": "APPROVED", "reason": "AUTHORIZATION_RETRIEVAL_SUCCESSFUL", "description": "Authorization was retrieved successfully." }, { "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": "218327", "original_processing_code": "218327" } }, { "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": "MERCHANT", "status": "APPROVED", "reason": "MERCHANT_VALID_STATUS", "description": "Merchant has valid status.", "additional_data": { "merchant_external_id": "FL-123456", "status": "ACTIVE", "marketplace_id": "102030" } }, { "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": "PAYMENT_METHODS_PERSISTENCE", "status": "APPROVED", "reason": "PAYMENT_METHODS_PERSISTENCE_CREATED", "description": "Payment methods record was created successfully." }, { "name": "ACCOUNT_ID", "status": "APPROVED", "reason": "ACCOUNT_ID_PERMITTED", "description": "Account ID is permitted.", "additional_data": { "document_number": "6XXXXXXXXXX9", "external_id": "", "name": "Test org" } }, { "name": "ORIGINAL_AUTHORIZATION", "status": "APPROVED", "reason": "ORIGINAL_AUTHORIZATION_APPROVED", "description": "Original authorization validation was approved." }, { "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." }, { "name": "PROGRAM", "status": "APPROVED", "reason": "PROGRAM_FOUND", "description": "Program was found.", "additional_data": { "program_type": "PRE-PAGO" } } ] } }, "Cancel authorization response": { "value": { "authorization_id": 2413411561, "tracking_id": "3277a9b7-81cd-403c-852a-d632b47fbcae", "account_id": 2417, "authorization_code": "MMEYFR", "response_code": "00", "denial_code": "", "custom_message": "", "datetime_utc": "2025-07-15T13:34:57.221Z", "number_of_installments": 2, "calculated_amounts": { "contract_amount": 10000, "principal_amount": 10000, "installment_amount": 5000, "additional_financial_details": null, "postings": {}, "rates": { "conversion_rate": 1 }, "installments": [ { "number": 1, "installment_amount": 5000, "principal_amount": 5000, "amortization_amount": 0 }, { "number": 2, "installment_amount": 5000, "principal_amount": 5000, "amortization_amount": 0 } ] }, "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": "AUTHORIZATION_RETRIEVAL", "status": "APPROVED", "reason": "AUTHORIZATION_RETRIEVAL_SUCCESSFUL", "description": "Authorization was retrieved successfully." }, { "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": "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": "MERCHANT", "status": "APPROVED", "reason": "MERCHANT_VALID_STATUS", "description": "Merchant has valid status.", "additional_data": { "marketplace_id": "FL-123456", "status": "ACTIVE", "merchant_external_id": "102030" } }, { "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": "PAYMENT_METHODS_PERSISTENCE", "status": "APPROVED", "reason": "PAYMENT_METHODS_PERSISTENCE_CREATED", "description": "Payment methods record 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": "ORIGINAL_AUTHORIZATION", "status": "APPROVED", "reason": "ORIGINAL_AUTHORIZATION_APPROVED", "description": "Original authorization validation was approved." }, { "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." }, { "name": "ACCOUNT_STATUS", "status": "SKIPPED", "reason": "ACCOUNT_STATUS_SKIPPED", "description": "Account status validation was skipped.", "additional_data": { "cause": "Cancellations are forced operations and does not need to run this validation." } }, { "name": "PROGRAM", "status": "APPROVED", "reason": "PROGRAM_FOUND", "description": "Program was found.", "additional_data": { "program_type": "PRE-PAGO" } }, { "name": "REMAINING_CANCELLATION_BALANCE", "status": "APPROVED", "reason": "REMAINING_CANCELLATION_BALANCE_APPROVED", "description": "Remaining cancellation balance validation for this authorization was approved." }, { "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." }, { "name": "PAYMENT_METHODS_PERSISTENCE", "status": "APPROVED", "reason": "PAYMENT_METHODS_PERSISTENCE_CREATED", "description": "Payment methods record was created successfully." } ] } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorsResponse" }, "examples": { "Invalid authorization payload": { "value": [ { "code": "WONA0001", "message": "Authorization Payload is invalid. It must be a valid JSON." } ] }, "MTI required": { "value": [ { "code": "WONA0004", "message": "MTI is required.", "details": "Field: mti" } ] }, "Entry mode required": { "value": [ { "code": "WONA0005", "message": "Entry mode is required.", "details": "Field: entry_mode" } ] }, "Processing code required": { "value": [ { "code": "WONA0006", "message": "Processing code is required.", "details": "Field: processing_code" } ] }, "Installment number required": { "value": [ { "code": "WONA0011", "message": "Number of installments is required and must be greater than 0.", "details": "Field: number_of_installments" } ] }, "Amount required": { "value": [ { "code": "WONA0012", "message": "Amount is required.", "details": "Field: amount" } ] }, "Amount can't be negative": { "value": [ { "code": "WONA0013", "message": "Amount can't be negative.", "details": "Field: amount" } ] }, "Initiator ID required": { "value": [ { "code": "WONA0015", "message": "Card ID, card number, document number, bank account, bank branch, or account ID is required to identify the account holder.\"" } ] }, "Network required": { "value": [ { "code": "WONA0016", "message": "Network is required.", "details": "Field: network" } ] }, "Invalid mti": { "value": [ { "code": "WONA0018", "message": "Invalid MTI.", "details": "Field: mti" } ] }, "Invalid entry mode": { "value": [ { "code": "WONA0019", "message": "Entry mode is invalid. It should have two or three characters.", "details": "Field: entry_mode" } ] }, "Original identifier required": { "value": [ { "code": "WONA0020", "message": "Original tracking ID or original authorization ID is required to identify the authorization.", "details": "Field: original_tracking_id or original_authorization_id" } ] }, "Amount must be greater than zero": { "value": [ { "code": "WONA0032", "message": "Amount must be greater than zero.", "details": "Field: amount" } ] }, "Beneficiary ID must be UUID": { "value": [ { "code": "WONA0033", "message": "Beneficiary_id must be a valid UUID.", "details": "Field: beneficiary_id" } ] }, "Invalid clearing type": { "value": [ { "code": "WONA0036", "message": "Invalid Clearing Type. It must be ONLINE or OFFLINE.", "details": "Field: clearing_type" } ] }, "Max amount exceeded": { "value": [ { "code": "WONA039", "message": "A maximum of 20 digits including two decimals is allowed for the amount field.", "details": "Field: amount" } ] }, "Invalid amount decimal places": { "value": [ { "code": "WONA040", "message": "The amount must have a maximum of two decimal places.", "details": "Field: amount" } ] }, "Invalid tracking ID size": { "value": [ { "code": "WONA041", "message": "Tracking ID must not have more than 50 characters.", "details": "Field: tracking_id" } ] }, "Invalid authorization date time format": { "value": [ { "code": "WONA042", "message": "Authorization date time must be in the UTC-0 RFC3339 format.", "details": "Field: authorization_datetime" } ] }, "Invalid posting date format": { "value": [ { "code": "WONA043", "message": "Authorization posting date must be in the YYYY-MM-DD format.", "details": "Field: posting_date" } ] }, "External calculation invalid contract amount": { "value": [ { "code": "EINS0004", "message": "Contract amount cannot be negative and must contain at most 2 decimal places.", "details": "Field: contract_amount" } ] }, "External calculation invalid principal amount": { "value": [ { "code": "EINS0005", "message": "Principal amount cannot be negative and must contain at most 2 decimal places.", "details": "Field: principal_amount" } ] }, "External calculation principal greater than contract amount": { "value": [ { "code": "EINS0006", "message": "Principal amount cannot be greater than contract amount.", "details": "Field: principal_amount" } ] }, "External calculation invalid installment number": { "value": [ { "code": "EINS0010", "message": "Number of installments should be greater than 0.", "details": "Field: number_of_installments" } ] }, "External calculation invalid installment info size": { "value": [ { "code": "EINS0011", "message": "Number of installments must be equal to the installments details provided." } ] }, "External calculation invalid installment amounts": { "value": [ { "code": "EINS0012", "message": "All installments amounts must be greater than 0 and must contain at most 2 decimal places." } ] }, "External calculation invalid sum installment": { "value": [ { "code": "EINS0015", "message": "Added installment amounts don't match the contract amount." } ] }, "External calculation invalid first payment date": { "value": [ { "code": "EINS0016", "message": "First payment date in the additional financial details is invalid.", "details": "Field: first_payment_date" } ] } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/responses/401Unauthorized" }, "examples": { "Unauthorized": { "value": { "message": "Access token is missing or invalid." } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/responses/403Forbidden" }, "examples": { "Forbidden": { "value": { "message": "The request has been lost." } } } } } }, "422": { "description": "Unprocessable request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorsResponse" }, "examples": { "Unprocessable authentication method": { "value": [ { "code": "EPAE0004", "message": "The method provided in the payload does not exist." } ] } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorsResponse" }, "examples": { "Platform authentication unexpected error": { "value": [ { "code": "EPAE0001", "message": "Unexpected error while processing the call to the authentication system." } ] }, "Platform authentication timeout error": { "value": [ { "code": "EPAE0002", "message": "Timeout error while processing the call to the authentication system." } ] } } } } } } } } } } ```