APIs
Sub-processorsAbout PismoContact us

Request authorization

post
https://sandbox.pismolabs.io/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 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.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params

Request authorization processing body.

Request payment methods authorization processing.

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.

string
required

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

string
enum
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)
Allowed:
string
required

Network originating this request.

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
object

Authentication object.

string

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

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).

string
enum

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.

Allowed:
bank
object

Identifies bank's information. If provided, both bank account and branch fields are REQUIRED.

string

Unique string identifier for the beneficiary associated with the account.

calculated_amounts
object

Calculated amounts for the authorization.

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.

string
enum

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).

Allowed:
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.

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.

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.

boolean
Defaults to false

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.

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.

metadata
object

Any valid json containing useful information for the flow. This information is used by the authorization platform. It is only be replicated to the events issued during the flow.

string

Sequential unique number that identifies this authorization.

integer
1 to 100

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

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.

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.

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.

boolean
Defaults to false

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

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
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.

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.

string

Transaction ID received with the authorization message.

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
object

Validation rules performed in the flow. Each key is a rule name (such as ACCOUNT_STATUS or LEDGER) and the value is its configuration.

authorization_validations
object

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.

Responses

Updated 2 days ago

Language
Credentials
Bearer
JWT
URL
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json

Updated 2 days ago