Payment Transaction Consultation Service
Query the payment transaction using the Omnichannel API. This one service must be called following a request from the Service Payment to check approval status or return status of this payment request.
As the transaction capture occurs at the POS in person, the service Transaction Status query must be called by Automation until the return of the status field is status=PPC (Payment Pending confirmation) or status=ERR (Error Making Payment). If the status of transaction is PPC, this service will return the response data from the payment.
Payment Transaction Inquiry can also be called in cases of communication error to check the current transaction status, which may whether or not it was received by the Omnichannel API.
Attention: The transaction query in the Omnichannel API DOES NOT query the status of the transaction at the acquirer / authorizer. This service returns the status of the transaction in the Omnichannel API database.
Example: If a payment transaction is confirmed on the Omnichannel API, but is reversed via telephone directly at the acquirer/authorizer, this reversal will not necessarily be reflected in the Omnichannel API transaction query service.
Call details#
Resource: /v1/sales/{sale_id}/payments/{nit}
HTTP Method: GET
URL Parameter:
| Parameter | Description | Type | Size | Required |
|---|---|---|---|---|
| nit | Payment transaction identifier in Omnichannel API, value returned from POST | AN | 64 | YES |
| sale_id | Identifier of the sale in the Omnichannel API, value returned from POST |
- Header parameters:
| Parameter | Description | Type | Size | Required |
|---|---|---|---|---|
| client_id | Client ID | AN | N/A | YES |
| site_id | Store Identification | AN | N/A | YES |
| Authorization | Bearer access_token value | AN | N/A | YES |
Response parameters#
If successful, the HTTP response code will be 200. Any other code should be interpreted as an error.
- Header parameters:
| Parameter | Description | Type | Size | Required |
|---|---|---|---|---|
| Content-Type | application/json; charset=utf-8 | AN | 16 | YES |
- Body: JSON
| Parameter | Description | Type | Size | Required |
|---|---|---|---|---|
| code | Payment Gateway response code. Any code other than ‘0’ means failure. In case of failure, consider that the transaction status will remain as Pending. | N | < 4 | YES |
| message | Optional response message that serves as diagnostic support for the developer (always in English) | AN | < 500 | YES |
| status | payment request status If POS has not yet started capturing the transaction, status is “1 – Aguardando POS” If POS has already started capturing the transaction, status is = “2 – Transação já iniciada (pagamento em andamento)” If the Omnichannel API has already received the transaction response (approved or denied, status = “3 – Transação processada” If the transaction capture was aborted at the POS, status = “4 – Transação cancelada” Only when status = 3 (Transaction processed) will the payment data be returned in the payment data set . | AN | YES | |
| payment | Object containing payment data (see specification below) | Object | Conditional Mandatory if the payment was successful and the status field is equal to 3-(Transaction processed) |
| Payment object | |||||
|---|---|---|---|---|---|
| Parameter | Description | Type | Size | Required | |
| status | Status of the payment transaction in the Omnichannel API. For more information, see the Shared Tables section. | AN | =3 | YES | |
| nit | Payment transaction identifier in the Omnichannel API. This field will only be displayed in Payment in multiple calls | NA | =64 | ||
| authorizer_code | Authorizer response code. | AN | < 10 | YES | |
| authorizer_message | Authorizer response message. | AN | < 500 | NO | |
| order_id | Order code sent by the store when creating the transaction. | AN | < 20 | YES | |
| merchant_usn | Unique sequential number sent by the store when creating the transaction. | N | < 12 | YES | |
| amount | Purchase value specified by the store (in cents) when creating the transaction. | N | < 12 | YES | |
| payment_method | Payment Method previously informed or selected during the transaction capture flow. | N | 3 | YES | |
| gateway_usn | Unique sequential number of the payment transaction at the Payment Gateway. | N | = 6 | YES (TODO: CONFIRM IF POS BIN IS RETURNING) | |
| List of objects containing transaction receipts. See the Complex Parameters section for more details. | List | YES | |||
| authorizer_id | Code of the authorizer used in the transaction. | N | < 4 | NO | |
| acquirer_id | Acquirer code used in the transaction. | N | < 4 | NO | |
| acquirer_name | Name of the acquirer used in the transaction. | AN | < 100 | NO | |
| authorizer_date | Payment effective date returned by the authorizer in the format DD-MM-AAAATHH:mm. Example: 13-07-2017T16:03 | D | = 16 | YES | |
| authorization_code | Authorization Code. | AN | < 6 | YES | |
| txidpix | Extended Authorization Code, present only in PIX transactions. | AN | < 99 | CONDITIONAL Mandatory if payment_method is equal to 3=(PIX) | |
| host_usn | NSU of the authorizer. | AN | < 15 | NO | |
| payment_date | Payment effective date in the format DD-MM-AAAATHH:mm. Example: 13-07-2017T16:03 | D | =16 | TODO: CONFIRM IF WE RECEIVED FROM BIN. | |
| issuer | Flag code returned by the authorizer. | AN | < 5 | TODO: CONFIRM IF WE RECEIVED FROM BIN. | |
| authorizer_merchant_id | Retailer's affiliation code with the authorizer. Identifier of the Host/acquirer in the Payment Gateway. | AN | < 100 | TODO: CONFIRM IF WE RECEIVED IT FROM BIN. | |
| terminal_merchant_id | Company data configured on the terminal that processed the transaction | TODO: CONFIRM IF WE RECEIVED IT FROM BIN. | |||
| terminal_id | Identification of the terminal that processed the transaction | TODO: CONFIRM IF WE RECEIVED IT FROM BIN. | |||
| card | Object containing card data (see specification below). | Object | NO | ||
| endtoendpix | Endtoend code sent in pix transactions | AN | >50 | CONDITIONAL Mandatory if payment_method is equal to 3=(PIX) | |
| invoice_data | Object with invoice fields for automation to issue with competent bodies or entities (see specification below) | Object | YES |
| Card object (inside payment) | ||||
|---|---|---|---|---|
| Parameter | Description | Type | Size | Required |
| masked_pan | Card pan, first 4 digits and last digits | to be defined | NO | |
| expiry_date | Card expiration date in MMAA format. | to be defined | NO | |
| entry_mode | Card entry mode (values to be defined) | to be defined | NO |
| invoice_data object (within payment) | ||||
|---|---|---|---|---|
| Parameter | Description | Type | Size | Required |
| host_cnpj | CNPJ of the debit/credit card accrediting network. Used for NFC-e | String | 0 or 14 | SIM |
| sat_host_id | Debit/credit card accreditor network code for SAT | String | 0 or 3 | YES |
| nfce_issuer_id | Debit/credit card flag confirms values defined by the NFC-e specification: ·01 - VISA ·02 - Mastercard ·03 - American Express ·04 - Sorocred ·99 - Others | String | 0 or 2 | YES |
Example#
Request and Response