API Reference
Last updated
Last updated
This reference section provides you with a complete and in-depth description of the Open Payment Platform API.
Test:
Live:
All requests must be sent over SSL
All requests are authenticated against an Authorization Bearer header with an access token. All the other data parameters are sent as body parameters, see for more information.
The API version is indicated in the request URL e.g. /v1/payments indicates version 1.
All changes made to the API are backwards compatible, hence any major features that are released, that would otherwise break existing implementations, will be released using a new version.
Our system expects data to be sent encoded in UTF-8. Using this Content-Type header can help:
application/x-www-form-urlencoded; charset=UTF-8
For each request you send to our API the HTTP status code of the response will already tell you the basic result.
200 - successful request
307 - temporary redirect
400 - bad request. This might either point to e.g. invalid parameters or values sent. It's also returned if the payment failed e.g. because the acquirer declined.
401 - invalid authorization header provided
403 - invalid access token provided
404 - requested resource or endpoint is not found. I.e. endpoint/url doesn't exist. This can also be caused by typos like POST /v1/payments instead of payments or wrong IDs like GET /v1/payments/{id} where no payment with {id} exists.
It is important to note that we have two test modes available to cause requests to be sent to our connector simulator or to the connector's own test platform, as required:
testMode=EXTERNAL causes test transactions to be forwarded to the processor's test system for 'end-to-end' testing
testMode=INTERNAL causes transactions to be sent to our simulators, which is useful when switching to the live endpoint for connectivity testing.
If no testMode parameter is sent, testMode=INTERNAL is the default behaviour
Parameter
Description
Format
Required
amount
Indicates the amount of the payment request. The dot is used as decimal separator.
N10.N2 [0-9]{1,10}(\.[0-9]{2})?
Required
currency
A3 [A-Z]{3}
Required
paymentBrand
The brand specifies the method of payment for the request. This is optional if you want to use brand detection for credit cards, if not then it is mandatory.
AN32 [a-zA-Z0-9_] {1,32}
Conditional
paymentType
The payment type for the request. You can send payment requests with one of the following types:
PA, Preauthorization: A stand-alone authorisation that will also trigger optional risk management and validation. A Capture (CP) with reference to the Preauthorisation (PA) will confirm the payment..
DB, Debit: Debits the account of the end customer and credits the merchant account.
CD, Credit: Credits the account of the end customer and debits the merchant account.
CP, Capture: Captures a preauthorized (PA) amount.
RV, Reversal: Reverses an already processed Preauthorization (PA), or Debit (DB) transaction. As a consequence, the end customer will never see any booking on his statement. A Reversal is only possible until a connector specific cut-off time. Some connectors don't support Reversals.
RF, Refund: Credits the account of the end customer with a reference to a prior Debit (DB) transaction. The end customer will always see two bookings on his statement. Some connectors do not support Refunds.
A2
Required
overridePaymentType[brand]
The payment type can be overriden for specific brands, for example: overridePaymentType[BOLETO]=PA overridePaymentType[KLARNA_INVOICE]=PA In such cases, the default payment type will be the one defined in paymentType parameter and every brand defined in overridePaymentType will have its own payment type. This parameter is only accepted during the checkout creation.
brand: AN32 [a-zA-Z0-9_]{1,32} value: A2
Optional
descriptor
Can be used to populate all or part of the Merchant Name descriptor, which often appears on the first line of the shopper's statement. The full use of this field depends on the Merchant Account configuration. Note: merchant.name can override any data sent in this field.
AN127 [\s\S]{1,127}
Optional
merchantTransactionId
Merchant-provided reference number, should be unique for your transactions. Some receivers require this ID. This identifier is often used for reconciliation.
AN255 [\s\S]{8,255}
Conditional
merchantInvoiceId
Merchant-provided invoice number, should be unique for your transactions. This identifier is not sent onwards.
AN255 [\s\S]{8,255}
Optional
transactionCategory
The category of the transaction, possible values are:
EC - eCommerce
MO - Mail order
TO - Telephone order
RC - Recurring
IN - Installment
PO - pos
PM - mpos
AN32 [a-zA-Z0-9]{0,32}
Optional
To make REST API calls, include the access token in the Authorization header with the Bearer authentication scheme.
Parameter / Header
Description
Format
Required
entityId
The entity for the request. By default this is the channel's ID. It can be the division, merchant or channel identifier. Division is for requesting registrations only, merchant only in combination with channel dispatching, i.e. channel is the default for sending payment transactions.
AN32 [a-f0-9]{32}
Conditional
Authorization Bearer <access-token>
Authorization header with Bearer authentication scheme.
Header
Required
The card data structure holds all information regarding a credit or debit card account.
Parameter
Description
Format
Required
card.holder
Holder of the credit card account
A128 {3,128}
Required
card.number
The PAN or account number of the card.
N19 [0-9]{12,19}
Required
card.expiryMonth
The expiry month of the card.
N2 (0[1-9]|1[0-2])
Required
card.expiryYear
The expiry year of the card.
N4 (19|20)([0-9]{2})
Required
card.cvv
The card security code or CVV
N4 [0-9]{3,4}
CONDITIONAL* INITIAL transactions = Required
Following are all the parameters needed for sending Card-on-File transactions
Parameter
Description
Format
Required
standingInstruction.type
The category of the transaction.
RECURRING: Recurring Transactions are transactions that are processed on a regular fixed interval for a pre-agreed or advised amount, where applicable. Recurring Transactions don't have a fixed duration and will continue to be processed until the cardholder cancels the agreement.
INSTALLMENT: Installment Payments are transactions that are processed on a regular fixed interval for a pre-agreed amount for a single purchase of good or services. Unlike Recurring Transactions, Installment Payments do have a fixed duration and shouldn't continue to be processed after the end of the agreed installment period.
UNSCHEDULED: An unscheduled credential-on-file transaction is like a recurring transaction but differs in that it does not happen at pre-agreed intervals. The classic example of such a transaction is when it is triggered by an event such as an amount threshold to ensure that a pay-as-you-go account always has a minimum available reserve.
UNSCHEDULED| INSTALLMENT| RECURRING
Optional
standingInstruction.mode
Indicating the mode of subsequent payment transaction.
INITIAL: The payment is the first of a series of payments. This first payment must contain additional data like the CVV code or 3D parameters to enable an initial authentication of the request.
REPEATED: The payment is a subsequent payment. It may not contain shopper authentication data like the CVV code or 3D parameters - the shopper is not present anymore.
INITIAL| REPEATED
Optional
standingInstruction.source
Indicating the type of subsequent payment transaction.
CIT: Cardholder initiated transaction.
MIT: Merchant initiated transaction.
CIT| MIT
Optional
The virtual account data structure is used to send account-based payments.
Parameter
Description
Format
Required
virtualAccount.accountId
The identifier of the shopper's virtual account.
AN100 [\s\S]{1,100}
Required
virtualAccount.password
The password of the shopper's virtual account. Required for only some brands.
AN100 [\s\S]{1,100}
Conditional
The customer data structure holds information about the customer/shopper such as their name, identification documents and contact details. The customer fields serve mixed purposes: On the one hand they are just for you to store information on your customers, but on the other hand they are also used and sometimes required for risk management and payment providers that require ID/mandate information. These use cases are noted in the parameters' descriptions.
Parameter
Description
Format
Required
customer.merchantCustomerId
An identifier for this customer. Typically this is the ID that identifies the shopper in the shop's system.
AN255 [\s\S]{1,255}
Optional
customer.givenName
The first name or given name of the customer. Required if you send in any other customer parameters, also required for some risk checks and payment providers. Will be truncated after 48 characters
AN [\s\S]
Conditional
customer.middleName
The middle name of the customer.
AN50 [\s\S]{2,50}
Optional
customer.surname
The last name or surname of the customer. Required if you send in any other customer parameters, also required for some risk checks and payment providers. Will be truncated after 48 characters
AN [\s\S]
Conditional
customer.birthDate
The birth day of the customer in the format yyyy-MM-dd, e.g. 1970-02-17
AN10 {19|20)([0-9]{2})-(0[1-9]|1[0-2])-(0[1-9]|1[0-9]|2[0-9]|3[0-1]}
Optional
customer.phone
The customer's phone number. Required for some risk checks.
AN25 [+0-9][0-9 \.()/-]{5,24}
Optional
customer.mobile
The customer's mobile number. Required for some risk checks.
AN25 [+0-9][0-9 \.()/-]{5,24}
Optional
customer.workPhone
The customer's phone number. Required for some risk checks.
AN25 [\s\S]{1,25}
Optional
customer.email
The customer's email address. Required for some risk checks and transmission of direct debit mandates.
AN128 [\s\S]{6,128}
Optional
customer.companyName
The customer's company name.
AN60 [\s\S]{1,60}
Optional
customer.identificationDocType
The type of identification document for the customer. Can be one of these three values: IDCARD, PASSPORT, TAXSTATEMENT. If this parameter is sent then customer.identificationDocId must be also sent. It is also mandatory for certain payment types (e.g. Boleto).
A12 [\s\S]
Conditional
customer.identificationDocId
The identifier of the identification document for the customer. If this parameter is sent then customer.identificationDocType must also be sent. It is also mandatory for certain payment types (e.g. Boleto).
AN64 [\s\S]{8,64}
Conditional
customer.ip
The customer's IP address.
AN255 [\s\S]{1,255}
Required
customer.browserFingerprint.id
The reference to the fingerprint of the shopper's browser, in most cases provided by some JavaScript library.
[\s\S]{1,255}
Optional
customer.browserFingerprint.value
The actual fingerprint value of the shopper's browser
[\s\S]{1,4096}
Optional
customer.status
A status of the customer. Currently two options- NEW, EXISTING.
A9 [\s\S]{1,255}
Optional
The shipping customer has the same fields than the billing customer, just as part of the shipping entity. That way you can ship to an entirely different customer.
Parameter
Description
Format
Required
shipping.customer.*
All the fields that are available under customer except shipping.customer.browserFingerprint.*
Same as for customer fields
Optional
The billing address holds the address of the customer. Information sent in the billing address data structure can optionally be used for risk checks such as AVS for card processing.
Parameter
Description
Format
Required
billing.street1
The door number, floor, building number, building name, and/or street name of the billing address
AN100 [\s\S]{1,100}
Conditional
billing.street2
The adjoining road or locality (if required) of the billing address
AN100 [\s\S]{1,100}
Conditional
billing.houseNumber1
Primary house number (door number or building number) of the billing address. If present, then billing.street1 is assumed to contain only the name of the street. Also, billing.street2 will be ignored.
AN100 [\s\S]{1,100}
Optional
billing.houseNumber2
Secondary house number (floor, building name) of the billing address. Used when more addresses are bundled to a same primary house number. If present, billing.houseNumber1 is also mandatory.
AN100 [\s\S]{1,100}
Optional
billing.city
The town, district or city of the billing address
AN80 [\s\S]{1,80}
Conditional
billing.state
The county, state or region of the billing address
AN50 [a-zA-Z0-9\.]{1,50}
Conditional
billing.postcode
The postal code or zip code of the billing address
AN30 [A-Za-z0-9]{1,30}
Conditional
billing.country
A2 [A-Z]{2}
Conditional
The shipping address holds the location and recipient of ordered goods. This can be used for risk processing or logistics.
Parameter
Description
Format
Required
shipping.street1
The door number, floor, building number, building name, and/or street name of the shipping address
AN100 [\s\S]{1,100}
Conditional
shipping.street2
The adjoining road or locality (if required) of the shipping address
AN100 [\s\S]{1,100}
Conditional
shipping.houseNumber1
Primary house number (door number or building number) of the shipping address. If present, then shipping.street1 is assumed to contain only the name of the street. Also, shipping.street2 will be ignored.
AN100 [\s\S]{1,100}
Optional
shipping.houseNumber2
Secondary house number of the shipping address (floor, building name). Used when more addresses are bundled to a same primary house number. If present, shipping.houseNumber1 is also mandatory.
AN100 [\s\S]{1,100}
Optional
shipping.city
The town, district or city of the shipping address
AN80 [a-zA-Z]{1,80}
Conditional
shipping.state
The county, state or region of the shipping address
AN50 [a-zA-Z0-9\.]{1,50}
Conditional
shipping.postcode
The postal code or zip code of the shipping address
AN30 [A-Za-z0-9]{1,30}
Conditional
shipping.country
A2 [A-Za-z]{2}
Conditional
shipping.method
Method of the shipping. One of the options: LOWEST_COST, CARRIER_DESIGNATED_BY_CUSTOMER, ELECTRONIC_DELIVERY, GROUND, INTERNATIONAL, MILITARY, NEXT_DAY_OVERNIGHT, OTHER, STORE_PICKUP, SAME_DAY_SERVICE, TWO_DAY_SERVICE, THREE_DAY_SERVICE
AN30 [A-Z_]{5,30}
Conditional
shipping.comment
A comment for the shipping
AN160 [\s\S]{1,160}
Conditional
shipping.expectedDate
The expected delivery date
AN10 {19|20)([0-9]{2})-(0[1-9]|1[0-2])-(0[1-9]|1[0-9]|2[0-9]|3[0-1]}
Optional
shipping.logisticsProvider
The logistics provider of the shipping
AN255 [\s\S]{1,255}
Optional
shipping.trackingNumber
The tracking number of the shipping
AN255 [\s\S]{1,255}
Optional
The merchant data structure holds information about you, the merchant (acceptor). These fields can be used to override the information that is shown on the cardholder statement. It can also be used for payment facilitators.
Parameter
Description
Format
Required
merchant.name
The name of the merchant/acceptor. When used this field will override the value sent as Merchant Name and will normally make up the first line of the card holder statement.
Typical usage would be of format {Merchant DBA Name}*{Description of product or service}.
AN100 [\s\S]{1,100}
Optional
merchant.city
The merchant's city, phone number, email or url. This normally makes up the second line of the card holder statement. It is typical for card present transactions to send the city of the location of transaction and for card not present transactions to send the phone, email or url that the shopper would be recognise.
AN100 [\s\S]{1,100}
Optional
merchant.street
The door number, floor, building number, building name, and/or street name of the merchant
AN100 [\s\S]{1,100}
Optional
merchant.postcode
The postal code or zip code of the merchant
AN10 [A-Za-z0-9\-]{1,10}
Optional
merchant.state
The county, state or region of the merchant
AN50 [a-zA-Z0-9]{1,50}
Optional
merchant.country
The country of the merchant
A2 [A-Za-z]{2}
Optional
merchant.phone
The merchants's phone number.
AN25 [a-zA-Z0-9\+-.]{0, 25}
Optional
merchant.mcc
The merchants's category code.
AN4 [a-zA-Z0-9]{0, 4}
Optional
merchant.submerchantId
Used only for MasterCard Payment Facilitators. The id of the sub-merchant.
AN100 [\s\S]{1,100}
Optional
The cart data structure holds product information about the shopping cart such as the product's ID, name, quantity and price. The cart items are counted up by changing the index-number [n], starting with 0. Example: cart.items[0].name=First Cart Item
Parameter
Description
Format
Required
cart.items[n].name
The name of the item in the shopping cart. Example: cart.items[0].name=First Cart Item
AN255 [\s\S]{1,255}
Conditional
cart.items[n].merchantItemId
The unique identifier of the item in the shopping cart.
AN255 [\s\S]{1,255}
Conditional
cart.items[n].quantity
The number of items in the shopping cart.
N5 [0-9]{1,5}
Conditional
cart.items[n].type
The type of the purchased item in the shopping cart.
AN255 [\s\S]{1,255}
Conditional
cart.items[n].sku
The sku cart item.
AN255 [\s\S]{1,255}
Optional
cart.items[n].price
The price of the item in the shopping cart. (including tax and discount). The item's price is independent of the quantity.
N13 [0-9]{1,10}\.[0-9]{2}
Conditional
cart.items[n].currency
The currency of the price of the shopping cart.
Conditional
cart.items[n].description
The description of the item in the shopping cart.
AN2048 [\s\S]{1,2048}
Conditional
cart.items[n].tax
The tax percentage applied to the price of the item in the shopping cart.
AN6 ^(100(\.00?)?)|([0-9]{1,2}(\.[0-9]{1,2})?)$
Conditional
cart.items[n].shipping
The shipping amount applied to the item in the shopping cart.
N10.N2 [0-9]{1,10}\.[0-9]{2}
Conditional
cart.items[n].discount
The discount percentage applied to the price of the item in the shopping cart.
N13 [0-9]{1,10}\.[0-9]{2}
Conditional
cart.items[n].giftMessage
Gift Message for the specific cart item
AN255 [\s\S]{1,255}
Optional
cart.items[n].shippingMethod
Shipping method for the cart item.
AN255 [\s\S]{1,255}
Optional
cart.items[n].shippingInstructions
Shipping instructions for the cart item.
AN255 [\s\S]{1,255}
Optional
cart.items[n].shippingTrackingNumber
Shipping tracking number for the cart item
AN255 [\s\S]{1,255}
Optional
cart.items[n].originalPrice
The cart item's price before discounts. The item's price is independent of the quantity.
AN255 [\s\S]{1,255}
Optional
Parameter
Description
Format
Required
createRegistration
If true, the payment details will be stored with the request. As part of the response, you will receive the parameter registration.id which you can use to reference the registration for later payments.
A5 true|false
Optional
Parameter
Description
Format
Required
recurringType
Used to indicate the type of recurring payment.
INITIAL: The payment is the first of a series of payments. This first payment has to contain additional data like the CVV code or 3D parameters to enable an initial authentication of the request.
REPEATED: The payment is a subsequent payment. It may not contain shopper authentication data like the CVV code or 3D parameters - the shopper is not present anymore.
A20 INITIAL|REPEATED
Optional
recurring.numberOfInstallments
The number of installments the payment should be split into.
N3
Optional
Description
Format
Required
customParameters[payment_retrial]
payment_retrial indicates whether a merchant-initiated payment request is a retrial (true), or if it is the first time the payment has been attempted (false).
Boolean [true | false]
Optional
customParameters[payment_attempt_number]
payment_attempt_number indicates the number of times a payment has been attempted.
payment_retrial=false implies payment_attempt_number=1
payment_retrial=true should be accompanied by a payment_attempt_number value greater than or equal to 2.
N [1-9][0-9]*
Optional
customParameters[payment_reference]
payment_reference is an identifier that is shared by all attempts (first attempt & retrials) for the same payment.
AN64 [\s\S]{8,64}
Optional
Custom parameters are unspecified fields that can be used to send custom data. The data sent in these fields are echoed back in the response.
Parameter
Description
Format
Required
customParameters[name]
A name value pair used for sending custom information. Note: customParameters that are sent from the client-side (e.g. for COPYandPAY) should be prepended with SHOPPER_*, for example customParameters[SHOPPER_customerId]
name: AN64 [a-zA-Z0-9\._]{3,64} value: AN2048 [\s\S]{0,2048}
Conditional
Asynchronous payment methods like 3D secure, online transfer or virtual wallets have additional steps in their workflow. The response to your initial payment request will be pending and contain a redirect URL to the receiver system that the shopper should be forwarded to.
Parameter
Description
Format
Required
shopperResultUrl
This URL will receive the result of an asynchronous payment. Must be sent URL encoded.
AN2048 [\s\S]{6,2048}
Conditional
notificationUrl
This URL will receive the asynchronous notification where applicable. Must be sent URL encoded.
AN2048 [\s\S]{6,2048}
Optional
The response parameters:
Parameter
Description
Format
Required
redirect.url
URL the the shopper must be redirected to in order to proceed.
AN2048 [\s\S]{6,2048}
Conditional
redirect.parameters[n].name
List of parameter names for the redirect.url. The corresponding parameter value is the same parameter number ending with .value like described in the line below.
AN255 [\s\S]{1,255}
Conditional
redirect.parameters[n].value
The parameter values corresponding to the names as described above.
AN255 [\s\S]{1,255}
Conditional
When you register a webhook, you'll receive notifications on the registered Url. These notifications are basically standard responses (wrapped in the "payload") of different types.
Parameter
Description
Format
Required
type
Type of notification
PAYMENT This type of notification is sent when payment is created or updated in the system.
REGISTRATION This type of notification is sent when we get new registration request, or the existing registration has been deleted.
(PAYMENT|REGISTRATION)
Required
action
Indicator of status change
CREATED e.g., When registration has been created.
UPDATED e.g., When registration has been updated.
DELETED e.g., When registration has been deleted.
(CREATED|UPDATED|DELETED)
Conditional
payload
Content of notification. If the notification type is payment or registration, payload will be identical to payment response you received.
JSON
Required
In addition to standard response parameters, these notifications specific are available:
Parameter
Description
Format
Required
presentationAmount
The presentation amount of the request.
N10.N2 [0-9]{1,10}\.[0-9]{2}
Conditional
presentationCurrency
The presentation currency of the request.
A3 [a-zA-Z]{3}
Conditional
The following parameters are used when calling the reporting endpoints.
Parameter
Description
Format
Required
date.from
The date from which the report data should start
AN10 {19|20)([0-9]{2})-(0[1-9]|1[0-2])-(0[1-9]|1[0-9]|2[0-9]|3[0-1]}
Required
date.to
The date on which the report data should end
AN10 {19|20)([0-9]{2})-(0[1-9]|1[0-2])-(0[1-9]|1[0-9]|2[0-9]|3[0-1]}
Required
The following parameters are additional parameters available for risk checks e.g. using the ReD Shield.
Parameter
Description
Format
Required
risk.channelId
Id of the channel in the risk system. This field is usually set up as a configuration, but in some situations you might want to use the dynamic request based option described here. For the ReD Shield this will cause a different set of rules to be executed. There the length is limited to AN12.
AN255 [\s\S]{1,255}
Optional
risk.serviceId
Id of the service in the risk system. This field is usually set up as a configuration, but in some situations you might want to use the dynamic request based option described here. For the ReD Shield this defines which fraud screening service to use. There the length is limited to AN1.
AN255 [\s\S]{1,255}
Optional
risk.amount
Amount for the risk request. The dot is used as decimal separator. Currently this parameter is used for both ReD Shield and 3D Secure. When performing the 3D Secure, if this parameter is present, its value will be used as the amount for the 3D Secure.
N10.N2 [0-9]{1,10}\.[0-9]{2}
Optional
risk.orderTimestamp
Timestamp of the order for the risk request. Format: yyyy-MM-dd hh:mm:ss (24h clock), e.g. 2015-12-17 22:00:04 By default our payment system sets a timestamp automatically. Use this field when the (payment) transaction was executed at a different time than sending the risk request at hand.
AN19 {(19|20)([0-9]{2})-(0[1-9]|1[0-2])-(0[1-9]|1[0-9]|2[0-9]|3[0-1] 0[0-2]1[0-9]:0[0-5]1[0-9]:0[0-5]1[0-9] }
Optional
risk.brand
Brand of the payment that is being checked. By default you can use the field paymentBrand instead of this one. However, if the payment isn't executed through the OPP you might have a different brand-format you can specify here.
AN255 [\s\S]{1,255}
Optional
risk.parameters[name]
A name value pair used for sending custom information related to the risk request.
name: AN64 [a-zA-Z0-9\._]{3,64} value: AN2048 [\s\S]{0,2048}
Optional
risk.merchantWebsite
Merchant's website URL
AN60 [\s\S]{1,60}
Optional
risk.accountToken
A merchant-set token for the account
AN64 [\s\S]{1,64}
Optional
Parameter
Description
Format
Required
id (/checkouts)
AN48 [a-zA-Z0-9.\-]{32,48}
required
id (/payments)
AN32 [a-zA-Z0-9]{32}
required
id (/registrations)
AN32 [a-zA-Z0-9]{32}
required
referencedId
In case of referenced payment (e.g., Capture or Refund), this fields included to see which payment was referenced. Note: This fields is only for webhook notification.
AN32 [a-zA-Z0-9]{32}
Conditional
paymentBrand
The payment brand of the request.
AN32 [a-zA-Z0-9_] {1,32}
Conditional
amount
The amount of the request.
N10.N2 [0-9]{1,10}\.[0-9]{2}
Conditional
currency
The currency of the request.
A3 [a-zA-Z]{3}
Conditional
descriptor
The descriptor of the request.
AN127 [\s\S]{1,127}
Conditional
result.code
AN11 [0-9\.]{2,11}
Required
result.description
A textual description explaining the result.code's meaning.
AN255 [\s\S]{0,255}
Optional
result.avsResponse
Contains the AVS response returned by the acquirer. It may include one the following result: A = Address does match, zip code does not match Z = Address does not match, zip code does match N = Address and zip code do not match U = Technical or logical error. AVS cannot be applied on card or address (not UK or US issuer), issuer is not available, etc. F = Address and Postal Code Matches
A1 [A-Z]{1}
Conditional
result.cvvResponse
Contains the CVV response returned by the acquirer. It may include one the following result:
M - CVV2 Match Indicates that the issuer was able to verify the CVV2 value provided by the merchant.
N - CVV2, CVC2, Discover CID or AMEX CID do not match Indicates that the issuer was not able to verify the CVV2 value provided by the merchant.
P - Not Processed Indicates that the issuer was unable to verify the CVV2 value provided by the merchant because either their verification system was not functioning, or not all of the information needed to verify the CVV2 value (such as the expiration date) was included in the request.
S - CVV2, CVC2, Discover CID or AMEX CID data is not present on the card, but the issuer indicated it should be present Indicates that the issuer was unable to perform CVV2 verification, and notifies the merchant that the card should contain a CVV2 value.
U - Unsupported by issuer or issuer is unable to process request Indicates that the issuer is not participating in the CVV2 service, or that the issue has not provided the card Brand with the required encryption keys needed to perform verification, or that STIP has responded with unavailable response.
A1 [A-Z]{1}
Conditional
resultDetails
A container for name value pair used for enriching the response with bank-specific response details. I.e. the actual parameters used within resultDetails are bank-specific. Example: resultDetails.AuthCode=123456
name: AN64 [a-zA-Z0-9\._]{3,64} value: AN2048 [\s\S]{0,2048}
Optional
resultDetails.AcquirerResponse
Represents the acquirer original response code retrieved from the acquirer directly.
AN2048 [\s\S]{0,2048}
Conditional
card.bin
The first six digits of the card.number
N6 [\d]{6}
Optional
card.holder
Holder of the credit card account
N6 [\d]{6}
Optional
card.expiryMonth
The expiry month of the card
N6 [\d]{2}
Optional
card.expiryYear
The expiry year of the card
N4 [\d]{4}
Optional
merchant.bankAccount.holder
Holder of the merchant's bank account
AN128 {4,128}
Required
merchant.bankAccount.number
The account number of the merchant's bank account. (IBAN for SEPA accounts)
AN64 [a-zA-Z0-9]{3,64}
Conditional
merchant.bankAccount.bic
The BIC (Bank Identifier Code (SWIFT)) number of the merchant's bank account.
AN11 [a-zA-Z0-9]{8}|[a-zA-Z0-9]{11}
Conditional
merchant.bankAccount.country
AN2 [a-zA-Z]{2}
Conditional
risk.score
Returns the score of the executed transaction risk checks. The value is a number from -99999 to +99999. Can be returned both for standalone risk requests and payment requests that include risk checks.
AN6 [-+]?[0-9]{5}
Conditional
Other
The response can also contain each of the data structures listed above, such as customer and billingAddress.
n/a
Conditional
buildNumber
Useful for support purposes.
AN255 [\s\S]{0,255}
Required
timestamp
The timestamp the response has generated.
date yyyy-MM-dd hh:mm:ssZ
Required
ndc
An internal unique identifier for the request.
AN65 [\s\S]{1,65}
Required
For payments you'll want more fine grained information to find out why a payment failed. You're getting this information in the .
The currency code of the payment request's amount ().
The country of the billing address ()
The country of the shipping address ()
A3 currency code
As described in the there are two ways to store a customer's data on the syste. Either directly POST to the registration endpoint or add the following parameter to a payment:
As described in the , all you have to do for sending recurring transactions is to flag the transaction with the following parameter:
The identifier of the checkout request that can be used to reference the payment later. You get this as the field id of a checkout's response and then should use it as the {id} part in step 2 and step 3 of the .
The identifier of the payment request that can be used to reference the payment later. You get this as the field id of a payment's response and then can use it as referencedPaymentId in the or as the {id} part of the URL for sending referencing requests.
The identifier of the registration request that can be used to reference the registration later. You get this either as the field id of a registration's response or as the field registrationId of a payment's response (if the request contained ). You should use it for requests referencing this registration as the {id} part of the URL.
The unique code that indicates the result status of the request. See the for more detailed information.
The country code of the merchant's bank account ().