--- title: "Request authorization" method: POST path: "/payment-methods/v1/authorization" tags: ["Payment methods"] --- # Request authorization `POST /payment-methods/v1/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](https://developers.pismo.io/pismo-docs/docs/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. ## Request body - PaymentMethodsAuthorizationRequest — Request payment methods authorization processing. - `amount` number — 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_code` string, 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) - `network` string, required — Network originating this request. - `account_id` integer — 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. - `authentication` Authentication — Authentication object. - `method` string — Authentication method. - `otp` is when the operation needs to be authenticated. - `transaction_signing` is when the operation has been authenticated already but needs to be validated. - `parameters` object — Authentication parameters will vary, depending on type of the method used. - `device_id` string — Device ID. Used in the `otp` authentication method. - `token` string — Authentication token. Used in the `otp` authentication method. - `user_id` string — User ID. Used in the `otp` authentication method. - `hash` string — Value generated at the time of authentication via OTP and intended for authentication via signing. Used in the `transaction_signing` authentication method. - `signing_data` object — Object that contains authorization information provided at time of signing. Used in the `transaction_signing` authentication method. - `authorization_code` string — Alphanumeric code generated in an authorization request and assigned to the authorization response. - `authorization_datetime` string, 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`. - `bank` object — Identifies bank's information. If provided, both bank `account` and `branch` fields are **REQUIRED**. - `account` string — Identifies the bank's account. This field should be used in the requests authorized based on the client's bank. **REQUIRED** together with the `bank.branch` field if `account_id`, `document_number`, or card information (`card.pan` or `card.stored_id`) are not provided. - `branch` string — Identifies the bank's branch. This field should be used in requests authorized based on the client's bank. **REQUIRED** together with the `bank.account` field if `account_id`, `document_number`, or card information (`card.pan` or `card.stored_id`) are not provided. - `beneficiary_id` string — Unique string identifier for the beneficiary associated with the account. - `calculated_amounts` CalculatedAmountsAuthorization — Calculated amounts for the authorization. - `contract_amount` number — Total amount of the authorization after calculation and addition of any necessary fees. - `description` string — Description of the plan. - `fees` object[] — List of applied fees on this calculation. - `type` string — Type of applied fee. For example, fixed, percentage, or any other type. - `amount` number — Calculated amount of this fee. - `rate` number — When using a percentage fee, this is the percentage rate used for calculating this fee. For example, the value `10` indicates 10%. - `interests` object[] — List of interests applied to this calculation. - `type` string — Type of applied interest. For example, weekly, monthly, annually, or any other type. - `amount` number — Calculated amount of this interest. - `rate` number — Percentage rate used for calculating this interest. For example, the value `9.99` indicates 9.99%. - `installments` object[] — List and details for each installment. - `number` integer — Order number of this installment in the hierarchy. - `contract_amount` number — Total amount of the installment after calculation and addition of any necessary fees. - `principal_amount` number — Total amount of the installment after calculation without the addition of any fees. - `amortization_amount` number — Amortization amount related to this installment. - `fees` object[] — List of applied fees on this calculation. - `type` string — Type of applied fee. For example, fixed, percentage, or any other type. - `amount` number — Calculated amount of this fee. - `rate` number — When using a percentage fee, this is the percentage rate used for calculating this fee. For example, the value `10` indicates 10%. - `interests` object[] — List of interests applied to this calculation. - `type` string — Type of applied interest. For example, weekly, monthly, annually, or any other type. - `amount` number — Calculated amount of this interest. - `rate` number — Percentage rate used for calculating this interest. For example, the value `9.99` indicates 9.99%. - `taxes` Tax - `currency` string — ISO-4217 alphabetic code (3 characters) for transaction currency. - `type` 'IOF' | 'IOF_DAILY' | 'INTEREST' — Tax type - `value` number — Tax value - `number_of_installments` integer — Number of installments in this calculation. - `plan_id` string — ID of the plan used to perform this calculation. - `principal_amount` number — Total amount of the authorization after calculation without the addition of any fees. - `taxes` Tax - `currency` string — ISO-4217 alphabetic code (3 characters) for transaction currency. - `type` 'IOF' | 'IOF_DAILY' | 'INTEREST' — Tax type - `value` number — Tax value - `total_annual_rate` number — Total interest percentage rate applied to this contract annually. - `total_monthly_rate` number — Total interest percentage rate applied to this contract monthly. - `additional_financial_details` AdditionalFinancialDetails — Additional information related to the authorization. - `effective_annual_cost` number — Total annual finance charge expressed as a percentage rate. - `effective_monthly_cost` number — Total monthly finance charge expressed as a percentage rate. - `annual_interest_rate` number — Percentage of interest charged over the course of a year. - `card` object — Contains all information related to the card used to perform this authorization. **REQUIRED** if `account_id`, `document_number`, or bank information (`bank.account` and `bank.branch`) are not provided. - `pan` string — 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. - `stored_id` string — 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. - `expiration_date` string — Card expiration date in the YYMM format entered by the cardholder at the authorization request. - `cvv2` string — CVV2 entered by the cardholder at the authorization request. - `track1_data` string — Track1 data captured at the terminal while performing an authorization with magnet stripe. - `track2_data` string — Track2 data captured at the terminal while performing an authorization with magnet stripe. - `pin_block` string — Pin block related to the password entered by the cardholder at the authorization request. - `cryptogram_data` object — Cryptogram data captured at the terminal while performing an authorization using chip. - `amount_authorized` string — Amount authorized referring to the tag 9F02. - `application_cryptogram` string — Application cryptogram information referring to the tag 9F26. - `application_interchange_profile` string — Application interchange profile referring to the tag 82. - `application_transaction_counter` string — Application transaction counter referring to the tag 9F36. - `application_version_number` string — Application version number referring to the tag 9F09. - `cardholder_verification_method` string — Cardholder verification method (CVM) results referring to the tag 9F34. - `cryptogram_information_data` string — Cryptogram information data referring to the tag 9F27. - `dedicated_file_name` string — Dedicated file name referring to the tag 84. - `interface_device_serial_number` string — Interface device serial number referring to the tag 9F1E. - `issuer_application_data` string — Issuer application data referring to the tag 9F10. - `issuer_authentication_data` string — Issuer authentication data referring to the tag 91. - `issuer_script_template` string — Issuer script template referring to the tag 71. - `pan_sequence_number` string — Pan sequence number referring to the tag 5F34. - `terminal_capabilities` string — Terminal capabilities information referring to the tag 9F33. - `terminal_country_code` string — Application interchange profile referring to the tag 9F1A. - `terminal_type` string — Terminal type referring to the tag 9F35. - `terminal_verification_result` string — Terminal verification result (TVR) referring to the tag 95. - `transaction_category_code` string — Transaction category code referring to the tag 9F53. - `transaction_currency_code` string — Transaction currency code referring to the tag 5F2A. - `transaction_date` string — Transaction date referring to the tag 9A. - `transaction_sequence_counter` string — Transaction sequence counter referring to the tag 9F41. - `transaction_type` string — Transaction type referring to the tag 9C. - `unpredictable_number` string — Unpredictable number referring to the tag 9F37. - `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_number` string — 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. - `description` string — 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_mode` string — 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_error` boolean — 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_id` string — ID of the installment plan that should be used to calculate this purchase. - `merchant` object — All information related to the merchant where the authorization took place. Only used for authorization requests with the `mti` values `0100` and `0120`. - `id` string — 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. **REQUIRED** if the `merchant` object is filled in. - `category_code` string — Merchant category code (MCC) of the merchant’s type of business or service. **REQUIRED** if the `merchant` object is filled in. - `name` string — Name of the merchant where the authorization is performed. **REQUIRED** if the `merchant` object is filled in. - `city` string — City of the merchant where the authorization is performed. - `country` string — Country code of the merchant where the authorization is performed. **REQUIRED** if the `merchant` object is filled in. - `terminal_id` string — ID of the terminal at the card acceptor location. - `marketplace_id` string — ID of the marketplace where this purchase took place. **REQUIRED** if the `merchant` object is filled in. - `metadata` string — 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](https://developers.pismo.io/pismo-docs/reference/get-started-with-pismo-apis#metadata). - `nsu` string — Sequential unique number that identifies this authorization. - `number_of_installments` integer — Number of installments in this authorization request. Purchases without installments should have the value 1. - `original_authorization_id` integer — 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_id` string — 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_date` string, 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_authorization` boolean — If set to `true`, this flag indicates that the operation is pre-authorized and requires additional confirmation. - `processing_code` string — 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_id` integer — 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_id` integer — 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. - `tid` string — Transaction ID received with the authorization message. - `tracking_id` string — 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_rules` ValidationRules — Rules that determine which validations are executed during the payment process.
Available validation rules: - `LEDGER` - `ACCOUNT_STATUS` - `FLEX_CONTROLS` - `RATES`
`force` is only supported for `LEDGER`. `override` is supported for `ACCOUNT_STATUS`, `FLEX_CONTROLS`, and `RATES`. - `authorization_validations` AuthorizationValidations — 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. - `is_device_registered` boolean — Indicates whether the device used for the operation is registered according to the financial institution's security policies. - `associated_ids` AssociatedIDs — External IDs used in the authorization flow. - `payment_id` string — External ID associated with the authorization. - `origin_id` string — External ID of the origin of the authorization. ## Response `200` Authorization was processed successfully, existing authorization with the corresponding `tracking_id` returned. - PaymentMethodsAuthorizationResponse — Payment methods authorization response. - `account_id` integer, required — Pismo ID of the account assigned as the owner of this request. - `authorization_code` string, 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_id` integer, required — Pismo ID of the authorization created for this request. - `calculated_amounts` object, required - `contract_amount` number — Total amount of the authorization after calculation with the addition of any necessary fees. - `principal_amount` number — Total amount of the authorization after calculation without the addition of any necessary fees. - `postings` object — Information about the applied fee or tax. - `rates` object — Rates used to calculate fees and taxes represented on Postings object. - `number_of_installments` integer, required — Number of installments in this authorization request. Purchases without installments should have the value `1`. - `response_code` string, required — 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. - `tracking_id` string, required — Tracking ID used to identify the authorization request. - `validation_results` object[], required - `name` string — Name of the evaluated rule. - `status` 'APPROVED' | 'REJECTED' | 'SKIPPED' — Identifies if the rule was approved, rejected, or skipped during the validation flow. - `reason` string — Status reason why the specific rule was approved, rejected, or skipped. - `description` string — Description of the validation result. - `additional_data` object — Additional data for the validation result. This varies from validation to validation, but every denied validation has the `denial_code` and `response_code` fields. - `custom_message` string — Message customized to describe the authorization response. - `denial_code` string — Denial code that indicates the reason why the request was denied. - `datetime_utc` string, date-time — Date and time when the authorization is created inside the Pismo platform in the UTC 0 time zone. ## Other responses - `201` — Authorization request was processed successfully - `400` — Bad Request - `401` — Unauthorized - `403` — Forbidden - `422` — Unprocessable request - `500` — Internal server error --- [API](https://skmtc.net/pismo/apis/platform-authentication.md) · [All operations](https://skmtc.net/pismo/apis/platform-authentication/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/pismo/platform-authentication/revisions/935b62e16de4/schema)