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.

403 - incorrect authentication information, e.g. one of the authentication.* parameters is wrong - please check them or contact us for correct parameters

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/paymnets instead of payments or wrong IDs like GET /v1/payments/{id} where no payment with {id} exists.

For payments you'll want more fine grained information to find out why a payment failed. You're getting this information in the result codes.

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), Debit (DB) or Credit (CD) 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) or Credit (CD) 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]=PAoverridePaymentType[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

Authentication

Authentication data is required in all server-to-server requests. The tutorials already provide you with a set of valid credentials. If you want to set up other credentials for your entities/channels, please contact us. Or, if you've got access rights for the backend, you'll find the data in the Merchant Info in Administration -> Account data

Parameter

Description

Format

Required

authentication.userId

The userId for the entity. Required to authenticate a server-to-server request

AN32[a-f0-9]{32}

Conditional

authentication.password

The password for the userId. Required to authenticate a server-to-server request

AN32[a-zA-Z0-9]{8,32}

Conditional

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

Virtual Account

The virtual account data structure is used to send account-based payments, e.g. PAYPAL.

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

Bank Account

The bank account data structure holds all the information that specifies a bank account. This is used for bank-account based payments, e.g. direct debits, SEPA and bank transfers. Collecting money from the shopper's bank account generally requires his approval. SEPA specific parameters - bankAccount.mandate.id, bankAccount.mandate.dateOfSignature,transactionDueDate are not used in the risk checks.

Parameter

Description

Format

Required

bankAccount.holder

Holder of the bank account

AN128{4,128}

Required

bankAccount.bankName

The name of the bank which holds the account.

AN255[\s\S]{1,255}

Conditional

bankAccount.number

The account number of the bank account. Either the number or the iban are required.

AN64[a-zA-Z0-9]{3,64}

Conditional

bankAccount.iban

The IBAN (International Bank Account Number) associated with the bank account. Either the number or the iban are required.

AN31[a-zA-Z]{2}[0-9]{2}[a-zA-Z0-9]{11,27}

Conditional

bankAccount.bankCode

The code associated with the bank account. Either the bankCode or the bic are required.

AN12[a-zA-Z0-9]{1,12}

Conditional

bankAccount.bic

The BIC (Bank Identifier Code (SWIFT)) number of the bank account. Either the bankCode or the bic are required.

Customer

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

Sex of the shopper, 'M' for male or 'F' for female

A1M|F

Optional

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[a-zA-Z0-9\+-.]{6, 25}

Optional

customer.mobile

The customer's mobile number. Required for some risk checks.

AN25[a-zA-Z0-9\+-.]{10, 25}

Optional

customer.workPhone

The customer's phone number. Required for some risk checks.

AN25[a-zA-Z0-9\+-.]{6,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

A12[\s\S]

Optional

customer.identificationDocId

The identifier of the identification document for the customer.

AN64[\s\S]{8,64}

Optional

customer.ip

The customer's IP address.

AN255[\s\S]{1,255}

Optional

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

Shipping customer

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

Billing Address

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

Merchant

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

Cart

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.

Tokenization and Registration

As described in the Tokenization Guide 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:

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.

A5true|false

Optional

Recurring

As described in the Recurring Payments Guide, all you have to do for sending recurring transactions is to flag the transaction with the following parameter:

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.

A20INITIAL|REPEATED

Optional

recurring.numberOfInstallments

The number of installments the payment should be split into.

N3

Optional

3D Secure

The 3D secure data structure is used to hold authentication data generated by the 3D secure MPI. This data structure can be used to send authentication when an external MPI is being used.
If 3D data is sent as part of the request the payment gateway will just pass through these values to the acquiring system.

Parameter

Description

Format

Required

threeDSecure.eci

The ECI for the 3D secure request. Required when using a third-party MPIExample: threeDSecure.eci=01

N20[1-8]{1}

Conditional

threeDSecure.verificationId

The 3D secure CAVV or AAV. Required when using a third-party MPI. Must be Base64 encoded.

AN64[\s\S]{64}

Conditional

threeDSecure.xid

The 3D secure xid if available. Must be Base64 encoded.

AN64[\s\S]{64}

Conditional

Custom Parameters

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 payments

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. The actual return format is JSON as shown in the example snippet 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

Webhook Notifications

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

Reporting

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

Giftcard

A giftcard allows you to send additional information for payments and risk checks that have a gift card.

Risk

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.

N9.N2[0-9]{1,9}\.[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.

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

Job

The following parameters are additional parameters available for scheduling payment jobs

Parameter

Description

Format

Required

job.name

The name of the job to be scheduled

AN64[\s\S]{1,64}

Optional

job.year

Here you can specify/limit which year(s) the job will run
You can specify specific year, or comma separated years or * which means endless.

(\d{4})?(\,\d{4})*|\*

Optional

job.month

Here you can specify/limit which year(s) the job will run
You can specify specific month, or comma separated months or * which means endless.

(\d{2})?(\,\d{2})*|\*

Optional

job.dayOfMonth

Here you can specify/limit which day(s) the job will run
You can specify specific day, or comma separated days or * which means endless. Note that you can't specify both dayOfMonth and dayOfWeek, only one should be specified

(\d{2})?(\,\d{2})*|\*

Optional

job.dayOfWeek

Here you can specify/limit which week day(s) the job will run
You can specify specific day, or comma separated days or * which means endless. Note that you can't specify both dayOfMonth and dayOfWeek, only one should be specified

(\d)?(\,\d)*|\*

Optional

job.hour

Here you can specify/limit which week hour(s) the job will run
You can specify specific hour, or comma separated hours or * which means endless.

(\d{2})?(\,\d{2})*|\*

Optional

job.minute

Here you can specify/limit which week minute(s) the job will run
You can specify specific minute, or comma separated minutes or * which means endless.

(\d{2})?(\,\d{2})*|\*

Optional

job.second

Here you can specify/limit which week second(s) the job will run
You can specify specific second, or comma separated minutes or * which means endless.

(\d{2})?(\,\d{2})*|\*

Optional

job.startDate

Here you can specify starting at which date/time this job should be executed

yyyy-MM-dd HH:mm:ss

Optional

job.endDate

Here you can specify at which date/time this job should be ended

yyyy-MM-dd HH:mm:ss

Optional

job.noticeUnit

Here you can specify the date/time unit of noticeNumber

"YEAR"|"MONTH"|"WEEK"|"DAY"|"HOUR"|"MINUTE"|"SECOND"

Optional

job.noticeNumber

The notice to deschedule the job before until duration end

Number

Optional

job.noticeCallable

When the notice could be callable?

ANYTIME|DURATION_END

Optional

job.durationUnit

Here you can specify the date/time unit of durationNumber

"YEAR"|"MONTH"|"WEEK"|"DAY"|"HOUR"|"MINUTE"|"SECOND"

Optional

job.durationNumber

The minimum time/date of the duration of the job

Number

Optional

job.expression

You can specify a cron expression here that represents how often the job will run
If you specify this parameter, then it will overrite (year,month,dayOfMonth,dayOfWeek,hour, minute and second) parameters values

See http://www.quartz-scheduler.org/documentation/quartz-2.x/tutorials/crontrigger.html

Optional

Response Parameters

Parameter

Description

Format

Required

id (/checkouts)

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

AN48[a-zA-Z0-9.\-]{32,48}

required

id (/payments)

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 backoffice tutorial or as the {id} part of the URL for sending referencing requests.

AN32[a-zA-Z0-9]{32}

required

id (/registrations)

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 createRegistration=true). You should use it for requests referencing this registration as the {id} part of the URL.

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.

N9.N2[0-9]{1,9}\.[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

The unique code that indicates the result status of the request. See the result codes for more detailed information.

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 MatchIndicates 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 ProcessedIndicates 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 presentIndicates 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.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.