API Reference

Introduction

This reference section provides you with a complete and in-depth description of the Primeiro Payment Platform API.

Hosts

Test: https://test.oppwa.com/
Live: https://oppwa.com/

Security / Authentication

All requests must be sent over SSL

All requests are authenticated against a particular entity using a username and password. Authentication data is sent as POST parameters, see Authentication Parameters for more information.

Versioning

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.

Encoding

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

HTTP Status Codes

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.

Testing

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

Credit Card Test Accounts

Brand	Number	CVV	Expiry Date
VISA	4200000000000000 (no 3D) 4711100000000000 (3D enrolled)	any 3 digits	any date after today
MASTER	5454545454545454 (no 3D) 5212345678901234 (3D enrolled)	any 3 digits	any date after today
AMEX	377777777777770 (no 3D) 375987000000005 (3D enrolled)	any 4 digits	any date after today

Test Bank Accounts (SEPA)

Country	IBAN	BIC
Austria (AT)	AT152011128161647502	GIBAATWWXXX
Germany (DE)	DE23100000001234567890	MARKDEF1100
Spain (ES)	ES9121000418450200051332	CAIXESBBXXX

This reference lists all the Primeiro Payment Platform parameters, grouped by their data structures.

Basic Payment

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	The currency code of the payment request's amount (ISO 4217).	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 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]=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

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.	AN32 [a-f0-9]{32}	Conditional

Card Account

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}	Optional
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

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.	AN11 [a-zA-Z0-9]{8}\|[a-zA-Z0-9]{11}	Conditional
bankAccount.country	The country code of the bank account (ISO 3166-1).	AN2 [a-zA-Z]{2}	Conditional
bankAccount.mandate.id	The id of the mandate for direct debit.	AN256 [a-zA-Z\-]{0,256}	Conditional
bankAccount.mandate.dateOfSignature	The date the direct debit mandate was signed.	AN10 {19\|20)([0-9]{2})-(0[1-9]\|1[0-2])-(0[1-9]\|1[0-9]\|2[0-9]\|3[0-1]}	Conditional
transactionDueDate	The due date of the transaction of the direct debit.	AN10 {19\|20)([0-9]{2})-(0[1-9]\|1[0-2])-(0[1-9]\|1[0-9]\|2[0-9]\|3[0-1]}	Conditional

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	A1 M\|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 [+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}	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	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.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	The country of the billing address (ISO 3166-1)	A2 [A-Z]{2}	Conditional

Shipping Address

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.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	The country of the shipping address (ISO 3166-1)	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

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.	N13 [0-9]{1,10}\.[0-9]{2}	Conditional
cart.items[n].currency	The currency of the price of the shopping cart.	A3 ISO 4217 currency code	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

Airline

The airline data structure holds passenger and trip leg airline information.
The airline passenger and leg items are counted up by changing the index-number [n], starting with 0. Example: airline.passengers[0].name=Jane Jones

Parameter	Description	Format	Required
airline.totalTaxAmount	The total amount of tax	N10.N2 [0-9]{1,10}\.[0-9]{2}	Conditional
airline.totalFeesAmount	The total fees	N10.N2 [0-9]{1,10}\.[0-9]{2}	Conditional
airline.totalFareAmount	The total fare	N10.N2 [0-9]{1,10}\.[0-9]{2}	Conditional
airline.ticketIssueDate	The date the booking/ticket was made	AN10 {19\|20)([0-9]{2})-(0[1-9]\|1[0-2])-(0[1-9]\|1[0-9]\|2[0-9]\|3[0-1]}	Conditional
airline.ticketIssueAddress	The address that issued the ticket	AN255 [\s\S]{1,255}	Conditional
airline.thirdPartyBooking	Indicates if the ticket was booked via a third party	AN255 [\s\S]{1,255}	Conditional
airline.bookingtype	The type of booking	AN255 [\s\S]{1,255}	Conditional
airline.ticketDeliveryMethod	The delivery method of the ticket	AN255 [\s\S]{1,255}	Conditional
airline.bookingRefNum	The booking reference number	AN255 [\s\S]{1,255}	Conditional
airline.agentName	The agent name	AN255 [\s\S]{1,255}	Conditional
airline.agentCode	The agent code	AN255 [\s\S]{1,255}	Conditional
airline.passengers[n].type	The passenger type	AN255 [\s\S]{1,255}	Conditional
airline.passengers[n].name	The name of the passenger	AN255 [\s\S]{1,255}	Conditional
airline.passengers[n].ticketRestricted	Indicates if the passenger has a restricted ticket	AN255 [\s\S]{1,255}	Conditional
airline.passengers[n].ticketNumber	The passenger's ticket number	AN255 [\s\S]{1,255}	Conditional
airline.passengers[n].status	The passenger status	AN255 [\s\S]{1,255}	Conditional
airline.passengers[n].phone	The passenger's phone	AN255 [\s\S]{1,255}	Conditional
airline.passengers[n].frequentFlyerNumber	The passenger's frequent flyer number	AN255 [\s\S]{1,255}	Conditional
airline.passengers[n].email	The passenger's email	AN255 [\s\S]{1,255}	Conditional
airline.passengers[n].dob	The passenger's date of birth	AN255 [\s\S]{1,255}	Conditional
airline.passengers[n].checkDigit	The check digit for the passenger	AN255 [\s\S]{1,255}	Conditional
airline.passengers[n].legs[n].ticketNumber	The ticket number for the leg	AN255 [\s\S]{1,255}	Conditional
airline.passengers[n].legs[n].taxAmount	The tax amount for the leg	N10.N2 [0-9]{1,10}\.[0-9]{2}	Conditional
airline.passengers[n].legs[n].stopOverAllowed	Indicates if a stop over is allowed	AN255 [\s\S]{1,255}	Conditional
airline.passengers[n].legs[n].restrictions	Indicates if there is restrictions for the leg	AN255 [\s\S]{1,255}	Conditional
airline.passengers[n].legs[n].flightNumber	The flight number for the leg	AN255 [\s\S]{1,255}	Conditional
airline.passengers[n].legs[n].feesAmount	The fees for the leg	N10.N2 [0-9]{1,10}\.[0-9]{2}	Conditional
airline.passengers[n].legs[n].fareBasis	The fare basis for the leg	AN255 [\s\S]{1,255}	Conditional
airline.passengers[n].legs[n].fareAmount	The fare amount for the leg	N10.N2 [0-9]{1,10}\.[0-9]{2}	Conditional
airline.passengers[n].legs[n].exchangeTicketNum	The exchange ticket number for the leg	AN255 [\s\S]{1,255}	Conditional
airline.passengers[n].legs[n].departureTaxAmount	The departure tax amount for the leg	N10.N2 [0-9]{1,10}\.[0-9]{2}	Conditional
airline.passengers[n].legs[n].departureCountry	The departure country for the passenger	AN255 [\s\S]{1,255}	Conditional
airline.passengers[n].legs[n].departureAirport	The departure airport for the passenger	AN255 [\s\S]{1,255}	Conditional
airline.passengers[n].legs[n].airlineName	The name of the airline for the leg	AN255 [\s\S]{1,255}	Conditional
airline.passengers[n].legs[n].airlineCode	The code of the airline for the leg	AN255 [\s\S]{1,255}	Conditional
airline.passengers[n].legs[n].departureTime	The departure time for the leg	AN255 [\s\S]{1,255}	Conditional
airline.passengers[n].legs[n].departureDate	The departure date for the leg	AN10 {19\|20)([0-9]{2})-(0[1-9]\|1[0-2])-(0[1-9]\|1[0-9]\|2[0-9]\|3[0-1]}	Conditional
airline.passengers[n].legs[n].arrivalCountry	The destination country for the leg	AN255 [\s\S]{1,255}	Conditional
airline.passengers[n].legs[n].arrivalAirport	The destination airport for the leg	AN255 [\s\S]{1,255}	Conditional
airline.passengers[n].legs[n].arrivalTime	The arrival time for the leg	AN255 [\s\S]{1,255}	Conditional
airline.passengers[n].legs[n].arrivalDate	The arrival date for the leg	AN10 {19\|20)([0-9]{2})-(0[1-9]\|1[0-2])-(0[1-9]\|1[0-9]\|2[0-9]\|3[0-1]}	Conditional
airline.passengers[n].legs[n].couponNumber	The coupon number for the leg	AN255 [\s\S]{1,255}	Conditional
airline.passengers[n].legs[n].classOfService	The class of service for the leg	AN255 [\s\S]{1,255}	Conditional
airline.passengers[n].legs[n].carrierCode	The carrier code for the leg	AN255 [\s\S]{1,255}	Conditional

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.	A5 true\|false	Optional
overrideHolder	If true, it allows to send in the card.holder or bankAccount.holder to override the empty holder from the registration/tokenization transaction. It applies only to that particular payment and does not change the holder value of the registration transaction. For one-click payment, the edit box appears as the replacement over the empty label to allow the user to input the new value for the holder. This parameter is available on prepare (and update) checkout step of COPYandPAY as well as when sending the payment over registration one-click payment Server-to-Server.	A5 true\|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.	A20 INITIAL\|REPEATED	Optional
recurring.numberOfInstallments	The number of installments the payment should be split into.	N3	Optional

Recurring Migration

To do a migration of recurring payment you need to do a registration (RG) with INITIAL transaction data that are send with the following parameters:

Parameter	Description	Format	Required
recurringMigration.paymentType	Indicates the payment type of the INITIAL request(DB\|CD\|PA).	A2	Mandatory
recurringMigration.amount	Indicates the INITIAL payment amount.	N8.N2[0-9]{1,8}(\.[0-9]{2})?	Optional
recurringMigration.requestTimestamp	Indicates the timestamp of the INITIAL payment request (e.g. 2018-11-27 10:42:39+0000).	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] }	Conditional
recurringMigration.connectorTxId1	Indicates INITIAL payment response details as received from the acquirer.	A128{3,128}	Conditional
recurringMigration.connectorTxId2	Indicates INITIAL payment response details as received from the acquirer.	A128{3,128}	Conditional
recurringMigration.connectorTxId3	Indicates INITIAL payment response details as received from the acquirer.	A128{3,128}	Conditional

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 MPI Example: threeDSecure.eci=01	N2 0[1-8]{1}	Conditional
threeDSecure.verificationId	The 3D secure CAVV or AAV. Required when using a third-party MPI. Must be Base64 encoded.	AN28 [\s\S]{28}	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 Primeiro Pay) 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.	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

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

Point Of Sale (POS)

The pos data structure holds information about transaction initiated with POS-terminal.

Parameter	Description	Format	Required
pos.deviceId	Serial number of the terminal.	N32 [0-9]{1,32}	Optional
pos.deviceType	Terminal type. Possible values: MIURA_SHUTTLE, MIURA_M007, MIURA_M010, VERIFONE_E105, VERIFONE_E315, VERIFONE_E335	AN32 [a-zA-Z0-9_]{1,32}	Optional
pos.encryptedPin.data	Encrypted online PIN data.	AN2048 [a-zA-Z0-9]{1,2048}	Optional
pos.encryptedPin.ksn	Key serial number to decrypt online PIN.	AN2048 [a-zA-Z0-9]{1,2048}	Optional
pos.encryptedSred.data	Encrypted account data (PAN/TRACK2/EXPIRY). SRED stands for "Secure Reading and Exchange of Data".	AN2048 [a-zA-Z0-9]{1,2048}	Optional
pos.encryptedSred.ksn	Key serial number to decrypt account data.	AN2048 [a-zA-Z0-9]{1,2048}	Optional
pos.entryMode	What interface was used by the terminal for the transaction. Possible values: MANUAL, MAGSTRIPE, MAGSTRIPE_AS_FALLBACK, ICC, NFC_ICC, NFC_MAGSTRIPE.	AN32 [a-zA-Z0-9_]{1,32}	Required
pos.iccDataRequest	Additional data returned by the card, including ARQC.	AN2048 [a-zA-Z0-9]{1,2048}	Optional
pos.location.accuracy	GPS accuracy.	N32 [0-9]{1,32}	Optional
pos.location.latitude	Latitude by GPS.	N12 \-?[0-9]{0,1}[0-9]{1}\.[0-9]{1-8}	Optional
pos.location.longitude	Longitude by GPS.	N13 \-?[0-1]?[0-9]{1,2}\.[0-9]{1-8}	Optional
pos.panSequenceNumber	Sequence number of the card, in case multiple were issued with the same PAN.	N32 [0-9]{1,32}	Optional
pos.pinEntryCapability	Indicates if the terminal is currently able to handle PIN. Possible values: PIN_ENTRY_AVAILABLE, PIN_ENTRY_UNAVAILABLE.	AN32 [a-zA-Z0-9_]{1,32}	Optional
pos.terminalId	Id assigned by the acquirer.	N32 [0-9]{1,32}	Required
pos.transactionSequenceNumber	Sequence number of the transaction, incremented after each transaction by the terminal.	N32 [0-9]{1,32}	Optional
pos.transactionSource	Indicator that this is a POS transaction. Currently should be always POS.	A3 POS	Optional

The response parameters:

Parameter	Description	Format	Required
pos.clearing.authorizationAcquirerCode	Code assigned by the acquirer. Used to print receipts.	AN2048 [a-zA-Z0-9]{1,2048}	Optional
pos.clearing.authorizationIssuerCode	Code assigned by the issuer. Used to print receipts.	AN2048 [a-zA-Z0-9]{1,2048}	Optional
pos.clearing.identifier	Transaction identifier assigned by the acquirer.	AN2048 [a-zA-Z0-9]{1,2048}	Optional
pos.merchantId	Merchant identifier assigned by the acquirer.	AN2048 [a-zA-Z0-9]{1,2048}	Optional
pos.iccDataResponse	Data returned by the issuer that has to be returned to the card, including ARPC.	AN2048 [a-zA-Z0-9]{1,2048}	Optional
pos.statusText	Text that has to be additionally printed on the receipt (instead of approved/declined).	AN2048 [a-zA-Z0-9]{1,2048}	Optional
pos.timestamp	Timestamp of the transaction with the acquirer.	date yyyy-MM-dd hh:mm:ss	Optional

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.

Parameter	Description	Format	Required
giftCard.message	Message that should be written on the gift card.	AN160 [\s\S]{2,160}	Optional
giftCard.type	Type of the Gift Card. One of the options: ANNIVERSARY, BIRTHDAY, CONGRATULATIONS, APRIL_FOOLS_DAY, EASTER, FATHERS_DAY, GRADUATION, HOLIDAY, SEASONS_GREETINGS, PASSOVER, KWANZAA, HALLOWEEN, MOTHERS_DAY, NEW_YEARS_DAY, BOSSES_DAY, ST_PATRICKS_DAY, SWEETEST_DAY, CHRISTMAS, BABY_SHOWER, THANKSGIVING, OTHER, VALENTINES_DAY, WEDDING, SECRETARYS_DAY, CHINESE_NEW_YEAR, HANUKKAH, CELEBRATE_FALL, GRANDPARENTS_DAY, INDEPENDENCE_DAY	AN16	Optional

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

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.	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	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 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	The country code of the merchant's bank account (ISO 3166-1).	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:ss	Required
ndc	An internal unique identifier for the request.	AN32 [\s\S]{1,32}	Required