Payment fields
| FIELD | DATATYPE | REQUEST | RESPONSE | SIZE | DESCRIPTION |
|---|---|---|---|---|---|
| apmType | String | - | (0) | 32 | This indicates the method of payment and admits these values: apple_pay stripe_link paypal |
| cardHolder | String | (M) | (O) | Unlimited (BD 400KB) | The first and last name of the end-consumer. |
| cardNumber | String | (M) | (O) | 50 | The card account number of the end-consumer. It will be returned with a mask. |
| cardVerificationCode | String | (M) | - | 4 | The card’s security code of the end-consumer. |
| expireMonth | String | (M) | (O) | 2 | The card’s expiration month of the end-consumer. |
| expireYear | String | (M) | (O) | 4 | The card’s expiration year of the end-consumer. |
| zipCode | String | (O) | (O) | 12 | The zip code associated with the billing address the end-consumer has on file for their credit card. |
| binInfo.cardBrand | String | - | (O) | 18 | The card’s brand of the end-consumer (VISA, Mastercard, Diners Club, American Express, Discover, JCB, Maestro, Carte Bleue, China Union Pay, Elo, Dankort, Hipercard, Mir, Troy, Private Label, Unknown). |
| binInfo.cardType | String | - | (O) | 18 | The card’s type of the end-consumer (Credit, Debit, Prepaid, Charge). |
| binInfo.country | String | - | (O) | 2 | This is the card’s country of the end-customer. |
| binInfo.cardSegment | String | - | (O) | 50 | This is the card segment informed in credit card IIN service. (Consumer, Commercial, Business, government, all, payouts) |
| binInfo.bankInfo.bank | String | - | (O) | 50 | Bank name from the end-customer card. |
| binInfo.bankInfo.website | String | - | (O) | 50 | Bank website from the end-customer card. |
| binInfo.bankInfo.phone | String | - | (O) | 18 | Bank contact from the end-customer card. |
| data | String | (M) | - | 2048 | This is the required information to perfrom the payment. In the case of a credit card, this would be the ciphered data (encrypted by exchanged key). In the case of payment with a token, this would be the token (uuid format). |
| isFallback | Boolean | - | (O) | true/false | Indicates whether the current transaction has used the main MID of the route or has used the fallback MID. |
| is3ds | Boolean | - | (O) | true/false | Indicates whether the current transaction passed through the 3DS process. |
| authorizationInfo | Object | - | (O) | - | Contains authorization details returned in the payment response. |
| authorizationInfo.eci | String | - | (O) | 2 | Value returned by directory servers (namely Visa, MasterCard, JCB, and American Express) indicating the outcome of authentication attempted on transactions enforced by 3DS. |
| authorizationInfo.eciDesc | String | - | (O) | - | Description of the Electronic Commerce Indicator (ECI) value. |
| authorizationInfo.avsResult | String | - | (O) | - | Result code of the Address Verification Service (AVS) validation performed on the cardholder's billing address. |
| authorizationInfo.authorisationId | String | - | (O) | - | Unique identifier provided by the issuing bank or payment provider indicating the transaction authorization. |
| liabilityShift | Boolean | - | (O) | true/false | Used when the liability for fraudulent chargebacks (stolen or counterfeit cards) shifts from you to the card issuer. It occurs when 3D secure payment is successfully authenticated. There is no liability shift for recurring transactions. |
| mid.id | String | - | (M) | 36 | Unique identifier for a Merchant. Format UUID. |
| mid.providerApi | String | - | (M) | 30 | Provider name (gateway) used for payment. |
| mid.paymentSolution | String | - | (O) | 30 | Solution used for payment. |
| notificationDate | Instant | - | (O) | 20 | The date and time when a transaction notification is sent in UTC. Format: ISO 8601 in UTC / YYYY-MM-DDTHH:mm:ssZ. |
| orderId | String | (M) | (M) | 36 | The unique identifier of the order. Format UUID. |
| paymentMethod | String | - | (M) | 25 | This indicates the method of payment and admits these values: credit_card_ciphered_data (payment form) credit_card_ciphered_values (payment form inputs iframe) credit_card_token alternative_payment_method |
| transactionId | String | - | (O) | 36 | The unique identifier of the transaction. Format UUID. Note that transactionId might not be included in the response if the transaction ID was not actually created correctly (e.g. due to invalid card number). |
| transactionStatus | String | - | (O) | 10 | The current status of a transaction. The transaction will start in_process and change to success, failed, in_process or waiting_user_interaction for asynchronous / 3DS payments. |
| transactionType | String | - | (O) | 10 | The transaction type, being the possible values payment, refund, RDR, Retrieval or chargeback. |
| tokenId | String | - | (O) | 36 | Token ID, only in case a token has been generated. Format UUID. |
| orderInfo.money.amount | BigDecimal | - | (O) | 38 | Total amount requested in the transaction. The amount of the decimal place depends on the currency. |
| orderInfo.money.currency | String | - | (O) | 3 | The currency of the transaction. Format: 3-character abbreviation according to ISO 4217. |
| orderInfo.description | String | - | (O) | Unlimited (BD 400KB) | Optional free text description for the merchant. It is usually helpful for the merchant as an internal reference to locate the transaction. |
| orderInfo.concept | String | - | (M) | Unlimited (BD 400KB) | Description on the settlement of the account holder’s account about a transaction (bank statement). |
| orderInfo.userInformation. .ip | String | - | (O) | IPV4(XXX.XXX.XXX.XXX) | The global (internet) IP address of the consumer's device. |
| orderInfo.userInformation. | String | - | (O) | Unlimited (BD 400KB) | The end-consumer’s email address. |
| orderInfo.userInformation. .country | String | - | (O) | 2 | The end-consumer’s country. |
| orderInfo.userInformation. .language | String | - | (O) | 2 | Language code according to ISO 639-1. It can be any of CZ, DA, EN, DE, ES, FI, FR, IT, NL, PL, GR, RO, RU, SV or TR. |
| orderInfo.userInformation. .customerId | String | - | (O) | 250 | A customer ID is an optional parameter which is sent by the merchant to identify the user within their business strategy. If the request contains the customer ID, the response will show the same information in the transaction result. |
| orderInfo.userInformation. .browserInformation.acceptHeader | String | - | (O) | Unlimited (BD 400KB) | This is the HTTP accept header as retrieved from the cardholder’s browser in the HTTP request. In case it is longer than 2048 it has to be truncated. It is strongly recommended to provide this field to prevent rejections from the ACS server side. |
| orderInfo.userInformation. .browserInformation.userAgentHeader | String | - | (O) | Unlimited (BD 400KB) | This is the User Agent as retrieved from the card holder’s browser in the HTTP request. In case it is longer than 256 Byte it has to be truncated. It is strongly recommended to provide this field to prevent rejections from the ACS server side. |
| orderInfo.userInformation. .browserInformation.screenHeight | Integer | - | (O) | Unlimited (BD 400KB) | Screen height received by the client. Positive values allowed only. |
| orderInfo.userInformation. .browserInformation.timeZone | Integer | - | (O) | Unlimited (BD 400KB) | Time zone received by the client. Allowed integer values between -720 and 840. |
| orderInfo.userInformation. .browserInformation.enableJava | Boolean | - | (O) | Unlimited (BD 400KB) | Indicates if java is enabled. |
| orderInfo.userInformation. .browserInformation.screenColorDepth | Enum | - | (O) | Unlimited (BD 400KB) | Supported screen color depth. Allowed values are: 1, 4, 8, 15, 16, 24, 32, 48. |
| orderInfo.userInformation. .browserInformation.windowSize | String | - | (O) | Unlimited (BD 400KB) | Indicates the client’s window size. Example: “200px“. |
| userInformation.browserInformation.fingerprint | String | - | (O) | 512 | Device/browser fingerprint ID. Optional field, ensure backward compatibility if not sent |
| orderInfo.userInformation. .billingAddress.name | String | - | (O) | Unlimited (BD 400KB) | The name of the billing person provided by the user for billing purposes. |
| orderInfo.userInformation. .billingAddress.street | String | - | (O) | Unlimited (BD 400KB) | The street provided by the user for billing purposes. |
| orderInfo.userInformation. .billingAddress.city | String | - | (O) | Unlimited (BD 400KB) | The city provided by the user for billing purposes. |
| orderInfo.userInformation. .billingAddress.postcode | String | - | (O) | Unlimited (BD 400KB) | The postcode provided by the user for billing purposes. |
| orderInfo.userInformation. .billingAddress.country | String | - | (O) | Unlimited (BD 400KB) | The country in ISO 3166-2 format provided by the user for billing purposes. |
| orderInfo.userInformation. .billingAddress.state | String | - | (O) | Unlimited (BD 400KB) | The state provided by the user for billing purposes. The ISO 3166-2 of the country. Example: “US-AK”. |
| orderInfo.generateToken | Boolean | - | (O) | true/false | This value is set to true when a cardholder card data was stored by the merchant for future transactions |
| orderInfo.domain | String | - | (O) | Unlimited (BD 400KB) | The URL to be used for proceeding with payment on the provider side. |
| orderInfo.parentTransactionId | String | - | (O) | 36 | This is the unique identifier of the referenced transaction. It is used for payment in which the consumer is not present and the merchants are the payment initiators instead. Format UUID. |
| orderInfo.customTag | String | - | (O) | Unlimited (BD 400KB) | The item or product to be purchased in the transaction. This variable is optional and can be used as additional information in the order. |
| orderInfo.paymentDetails.type | String | - | (O) | Unlimited (BD 400KB) | Possible values: consumer_initiated, recurrence or credit_card_present. Required if payment details are informed. consumer_initiated: when the order is created by the consumer and it is going to pay by token. recurrence: when the order is created by the merchant and it is going to pay by token. Exceptionally, the initial recurrence could be paid by credit card. credit_card_present: when the order is created by the consumer and it is going to paid by credit card. |
| orderInfo.paymentDetails.minPeriod | Integer | - | (O) | 32 | Minimum period in days to charge a recurrence. Minimum value is 1. |
| orderInfo.paymentDetails.sequence | String | - | (O) | Unlimited (BD 400KB) | Possible values: sequence one of: initial, recurring or final. initial: first order of a recurrence recurring: order of a recurrence final: final order of a recurrence |
| orderInfo.items.name | String | - | (O) | 512 | Name of the product or service |
| orderInfo.items.sku | String | - | (O) | 512 | Stock Keeping Unit identifier |
| orderInfo.items.quantity | Integer | - | (0) | - | Number of units. Must be ≥ 1 |
| orderInfo.items.url | String | - | (O) | 512 | URL to product/service details (optional) |
| orderInfo.items.unitPrice | decimal | - | (O) | - | Price per unit. Must be > 0 |
| orderInfo.items.category | String | - | (O) | 512 | Category of the item (e.g., books, services) |
| orderInfo.items.tax | decimal | - | (O) | - | Tax amount for the item (optional) |
| operationResult.chargedAmount.amount | BigDecimal | - | (O) | 38 | Amount charged by the acquirer. |
| operationResult.chargedAmount.currency | String | - | (O) | 3 | Currency charged by the acquirer. Format: 3-character abbreviation according to ISO 4217. |
| errorMessage | String | - | (O) | Unlimited (BD 400KB) | Error message in case the payment failed. |
| notificationUrl | String | - | (O) | Unlimited (BD 400KB) | The URL to which any transaction state change notification will be sent. When this parameter is not present, the default notification URL specified in the merchant configuration is used instead. |
| redirectUrl.fail | String | - | (O) | Unlimited (BD 400KB) | The URL to which the consumer will be redirected after he has canceled a payment or payment has failed. This is normally a page on the merchant’s website. |
| redirectUrl.success | String | - | (O) | Unlimited (BD 400KB) | The URL to which the consumer will be redirected after a successful payment. This is normally a success confirmation page on the merchant’s website. |
| redirectUrl.threeDSChallengeResult | String | - | (O) | Unlimited (BD 400KB) | The URL where the consumer wants to receive the result of the challenge for 3DS payments. Format: URI. |
| threeDSSupport | String (Enum) | - | (O) | 13 | It indicates the interest level in paying the order through the 3DS process. This attribute admits the following values: no_3ds indifferent preferred_3ds required_3ds |
| orderInfo.purchaseId | String | (O) | - | Unlimited (BD 400KB) | Used to check whether a given order was already processed. |
| version | Integer | - | (M) | 32 | Indicates the API process version for the payment. |
| 3DS v2.0 FIELDS | |||||
| threeDSDetails. .cardHolderAccountInformation. .accountAge | String (Enum) | - | (O) | 17 | Period of time for which the cardholder has had an account with the 3DS requester. This attribute admits the following values: no_account: no account, guest check-out. new_account: created during this transaction. less_one_month: created for less than 30 days. one_to_two_months: created between 30−60 days. more_two_months: created for more than 60 days. |
| threeDSDetails. .cardHolderAccountInformation. .accountLastChangeDate | String | - | (O) | 10 | Date in which the cardholder’s account with the 3DS Requestor was last changed, including billing or shipping address, new payment account, or new user(s) added. Format: ISO 8641/ YYYY-MM-DD. |
| threeDSDetails. .cardHolderAccountInformation. .accountLastChangeAge | String (Enum) | - | (O) | 17 | Period of time since the cardholder’s account information with the 3DS requester was last changed, including billing or shipping address, new payment account, or new user(s) added. This attribute admits the following values: no_account: no account, guest check-out. new_account: created during this transaction. less_one_month: created for less than 30 days. one_to_two_months: created between 30−60 days. more_two_months: created for more than 60 days. |
| threeDSDetails. .cardHolderAccountInformation. .accountDate | String | - | (O) | 10 | Date in which the cardholder opened the account with the 3DS Requestor. Format: ISO 8641 / YYYY-MM-DD. |
| threeDSDetails. .cardHolderAccountInformation. .accountPasswordDate | String | - | (O) | 10 | Date in which the cardholder’s account with the 3DS requester had a password change or account reset. Format: ISO 8641 / YYYY-MM-DD. |
| threeDSDetails. .cardHolderAccountInformation. .accountPasswordAge | String (Enum) | - | (O) | 17 | Period of time since the cardholder’s account with the 3DS requester had a password change or account reset. This attribute admits the following values: no_account: no account, guest check-out. new_account: created during this transaction. less_one_month: created for less than 30 days. one_to_two_months: created between 30−60 days. more_two_months: created for more than 60 days. |
| threeDSDetails. .cardHolderAccountInformation. .accountPurchaseCount | Integer | - | (O) | 9999 | Number of purchases with this cardholder account during the previous six months. |
| threeDSDetails. .cardHolderAccountInformation. .accountStoredCardAttempts | Integer | - | (O) | 999 | Number of add card attempts in the last 24 hours. |
| threeDSDetails. .cardHolderAccountInformation. .accountDailyTransactions | Integer | - | (O) | 999 | Number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous 24 Hours. |
| threeDSDetails. .cardHolderAccountInformation. .accountYearlyTransactions | Integer | - | (O) | 999 | Number of transactions (successful and abandoned) for this cardholder account with the 3DS Requestor across all payment accounts in the previous year. |
| threeDSDetails. .cardHolderAccountInformation. .accountEnrollmentDate | String | - | (O) | 10 | Date in which the payment account was enrolled in the cardholder’s account with the 3DS requester. Format: ISO 8641 / YYYY-MM-DD. |
| threeDSDetails. .cardHolderAccountInformation. .accountEnrollmentAge | String (Enum) | - | (O) | 17 | Period of time since the payment account was enrolled in the cardholder’s account with the 3DS requester. This attribute admits the following values: no_account: no account, guest check-out. new_account: created during this transaction. less_one_month: created for less than 30 days. one_to_two_months: created between 30−60 days. more_two_months: created for more than 60 days. |
| threeDSDetails. .cardHolderAccountInformation. .accountShippingDate | String | - | (O) | 10 | Date in which the shipping address used in this transaction was first used with the 3DS requester. Format: ISO 8641/ YYYY-MM-DD. |
| threeDSDetails. .cardHolderAccountInformation. .accountShippingAge | String (Enum) | - | (O) | 17 | Period of time since the shipping address used for the transaction was first used with the 3DS requester. This attribute admits the following values: no_account: no account, guest check-out. new_account: created during this transaction. less_one_month: created for less than 30 days. one_to_two_months: created between 30−60 days. more_two_months: created for more than 60 days. |
| threeDSDetails. .cardHolderAccountInformation. .accountShippingEqual | String (Enum) | - | (O) | 22 | Indicates whether the cardholder name on the account is identical to the shipping name used in this transaction. This attribute admits the following values: account_name_identical account_name_different |
| threeDSDetails. .cardHolderAccountInformation. .accountSuspiciousActivity | String (Enum) | - | (O) | 31 | Indicates whether the 3DS Requestor has experienced suspicious activity (including previous fraud) on the cardholder account. This attribute admits the following values: no_suspicious_activity_observed suspicious_activity_observed |
| threeDSDetails. .merchantRiskIndicator.deliveryEmailAddress | String | - | (O) | 254 | For electronic delivery, the email address to which the merchandise was delivered. |
| threeDSDetails. .merchantRiskIndicator.deliveryTimeframe | String (Enum) | - | (O) | 25 | Indicates the merchandise delivery timeframe. This attribute admits the following values: electronic_delivery same_day_shipping overnight_shipping two_or_more_days_shipping |
| threeDSDetails. .merchantRiskIndicator.giftCardAmount | Integer | - | (O) | 38 | For prepaid or gift card purchase, the total purchase amount of prepaid or gift card(s) in major units (for example, USD 123.45 is 123). |
| threeDSDetails. .merchantRiskIndicator.giftCardCount | Integer | - | (O) | 99 | For prepaid or gift card purchase, total count of individual prepaid or gift card(s)/code(s) purchased. |
| threeDSDetails. .merchantRiskIndicator.giftCardCurrency | String | - | (O) | 3 | For prepaid or gift card purchase, ISO 4217 three-digit currency code of the gift card. |
| threeDSDetails. .merchantRiskIndicator.preOrderDate | String | - | (O) | 10 | For a pre-ordered purchase, the expected date that the merchandise will be available. Format: ISO 8641 / YYYY-MM-DD. |
| threeDSDetails. .merchantRiskIndicator.preOrderAvailability | String (Enum) | - | (O) | 21 | Indicates whether the cardholder is placing an order for merchandise with a future availability or release date. This attribute admits the following values: merchandise_available future_availability |
| threeDSDetails. .merchantRiskIndicator.reorderItemsInd | String (Enum) | - | (O) | 18 | Indicates whether the cardholder is reordering previously purchased merchandise. This attribute admits the following values: first_time_ordered reordered |
| threeDSDetails. .merchantRiskIndicator.shippingIndicator | String (Enum) | - | (O) | 32 | Indicates the shipping method chosen for the transaction. Merchants must choose the shipping indicator value that most accurately describes the cardholder’s specific transaction, not their general business. If one or more items are included in the sale, use the shipping indicator value for the physical goods, or if they are all digital goods, use the shipping indicator value that describes the most expensive item. This attribute admits the following values: ship_cardholders_billing_address: ship to cardholder’s billing address. ship_another_verified_address: ship to another verified address on file with merchant. ship_another_address: ship to address that is different from the cardholder’s billing address. ship_to_store: ship to store / pick-up at local store. Store address shall be populated in shipping address fields. digital_goods: includes online services, electronic gift cards and redemption codes. travel_and_event_tickets: travel and Event tickets, not shipped. others: for example, gaming, digital services not shipped, e-media subscriptions, etc. |
| threeDSDetails. .threeDSRequestorAuthenticationInfo. .threeDSReqAuthData | String | - | (O) | 20000 | Data that documents and supports a specific authentication process. In the current version of the specification, this data element is not defined in detail, however the intention is that for each 3DS requester authentication method, this field carries data that the ACS can use to verify the authentication process. E.g., if the 3DS requester authentication method is: login_using_federated_id: then this element can carry information about the provider of the federated ID and related information. login_using_fido_authenticator: then this element can carry the FIDO attestation data (including the signature). login_using_fido_authenticator_data_signed: then this element can carry FIDO Attestation data with the FIDO assurance data signed. src_assurance_data: then this element can carry the SRC assurance data. |
| threeDSDetails. .threeDSRequestorAuthenticationInfo. .threeDSReqAuthMethod | String (Enum) | - | (O) | 42 | Mechanism used by the cardholder to authenticate to the 3DS requester. This attribute admits the following values: no_3ds_authentication: no 3DS requester authentication occurred - i.e. cardholder “logged in” as guest. login_using_own_credentials: login to the cardholder account at the 3DS requester system using 3DS requester’s own credentials. login_using_federated_id: login to the cardholder account at the 3DS requester system using federated ID. login_using_issuer_credentials: login to the cardholder account at the 3DS requestrr system using issuer credentials. login_using_third_party_authentication: login to the cardholder account at the 3DS Requestor system using third-party authentication. login_using_fido_authenticator: login to the cardholder account at the 3DS requester system using FIDO authenticaton. login_using_fido_authenticator_data_signed: login to the cardholder account at the 3DS Requestor system using FIDO authenticator (FIDO assurance data signed). src_assurance_data: SRC assurance data. |
| threeDSDetails. .threeDSRequestorAuthenticationInfo. .threeDSReqAuthTimestamp | String | - | (O) | 20 | Date and time in UTC of the cardholder authentication. Format: ISO 8601 in UTC / YYYY-MM-DDTHH:mm:ssZ. |
| threeDSDetails. .threeDSRequestorPriorTransactionAuthenticationInfo. .threeDSReqPriorAuthData | String | - | (O) | 2048 | Data that documents and supports a specific authentication process. In the current version of the specification this data element is not defined in detail, however the intention is that for each 3DS requester authentication method, this field carries data that the ACS can use to verify the authentication process. In future versions of the specification, these details are expected to be included. |
| threeDSDetails. .threeDSRequestorPriorTransactionAuthenticationInfo. .threeDSReqPriorAuthMethod | String (Enum) | - | (O) | 31 | Mechanism used by the cardholder to authenticate beforehand with the 3DS requester. This attribute admits the following values: acs_frictionless_authentication: frictionless authentication occurred by ACS. acs_cardholder_challenge: cardholder challenge occurred by ACS. avs_verified: AVS verified. other_issuer_method: any other mechanism not listed above. |
| threeDSDetails. .threeDSRequestorPriorTransactionAuthenticationInfo. .threeDSReqPriorAuthTimestamp | String | - | (O) | 20 | Date and time in UTC of the prior cardholder authentication. Format: ISO 8601 in UTC / YYYY-MM-DDTHH:mm:ssZ. |
| threeDSDetails. .threeDSRequestorPriorTransactionAuthenticationInfo. .threeDSReqPriorRef | String | - | (O) | 36 | This data element provides additional information to the ACS to determine the best approach for handling a request. |
| threeDSDetails. .acsRenderingType. acsInterface | String (Enum) | - | (O) | 9 | This is the ACS interface that the challenge will present to the cardholder. This attribute admits the following values: native_ui html_ui |
| threeDSDetails. .acsRenderingType. acsUiTemplate | String (Enum) | - | (O) | 13 | Identifies the UI template format that the ACS first presents to the consumer. Valid values for each Interface: Native UI: text, single_select, multi_select and OOB. HTML UI: all values. Note that html_other is only valid in combination with html_ui. If used with native_ui, the DS will respond with an error. This attribute admits the following values: text single_select multi_select OOB html_other |
| threeDSDetails. .deviceRenderingOptionsSupported.sdkInterface | String (Enum) | - | (O) | 6 | Lists all of the SDK Interface types that the device supports for displaying specific challenge user interfaces within the SDK. This attribute admits the following values: native html both |
| threeDSDetails. .deviceRenderingOptionsSupported.sdkUiType | String (Enum) | - | (O) | 13 | Lists all UI types that the device supports for displaying specific challenge user interfaces within the SDK. Valid values for each Interface: Native UI: text, single_select, multi_select and OOB. HTML UI: all values. Currently, all SDKs need to support all UI types. In the future, however, this may change (for example, smart watches may support a UI Type not yet defined by this specification). This attribute admits the following values: text single_select multi_select OOB html_other |