PrimeiroPay
Search…
API Parameters Reference
Introduction
This reference section provides you with a complete and in-depth description of the PrimeiroPayment 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 an Authorization Bearer header with an access token. All the other data parameters are sent as body parameters, see Authentication Parameters for more information.
Throttling
Throttling is the process of limiting the number of requests submitted to a given operation in a given amount of time. Throttling protects the web service from being overwhelmed with requests and ensures providing a healthy web service.
Following throttling values has been configured:
Live system
Show throttling details
Test system
Show throttling details
Requests which will be affected by throttling, will be rejected with following return code:
1
{
2
"buildNumber":"[email protected] 06:31:46 +****",
3
"id":"8ac9a4a8658afc790165a3f0e436198d",
4
"ndc":"8acda4c9635ea2d90163636f0a462510_ebb07f3e26e942908d6eeed03a813237",
5
"result":{
6
"code":"800.120.100",
7
"description":"Too many requests. Please try again later."
8
},
9
"timestamp":"2018-09-04 09:42:33+0000"
10
}
Copied!
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-8HTTP 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.
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/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=EXTERNALcauses test transactions to be forwarded to the processor's test system for 'end-to-end' testingtestMode=INTERNALcauses 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 behaviourCredit 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 PrimeiroPayment 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. The amount is the only amount value which is processing relevant. All other amount declarations like taxAmount or shipping.cost are already included.
N10.N2 [0-9]{1,10}(\.[0-9]{2})?
Required
taxAmount
Indicates the tax amount of the payment request. The dot is used as decimal separator.
N10.N2 [0-9]{1,10}(\.[0-9]{2})?
Conditional
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), 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]=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
merchantMemo
Merchant-provided additional information. The information provided is not transaction processing relevant. It will appear in reporting only.
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
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 required to authorize the request. This should be the channel entity identifier. In case channel dispatching is activated then it should be the merchant entity identifier.
AN32 [a-f0-9]{32}
Conditional
Authorization Bearer <access-token>
Authorization header with Bearer authentication scheme. Access token can be taken from the backend UI under Administration > Account data > Merchant / Channel Info only if you have specific administration rights.
Header
Required
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
Apple Pay
There are two possible APIs for Apple Pay:
Apple Pay with encrypted payment token
You can send the encrypted payment token as-is. We will do the decryption and process the transaction.
Parameter
Description
Format
Required
applePay.paymentToken
The encrypted payment token created by Apple
Defined by Apple
Required
Apple Pay with decrypted card information
You can do the decryption by yourself and send us the decrypted card information with the usual card API: card.number, card.expiryMonth, card.expiryYear, threeDSecure.verificationId, threeDSecure.eci, and the following parameter:
Parameter
Description
Format
Required
applePay.source
Indicates the source of Apple Pay
web|app
Required
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
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.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 \.()/-]{7,25}
Optional
customer.mobile
The customer's mobile number. Required for some risk checks.
AN25 [+0-9][0-9 \.()/-]{5,25}
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.browser.acceptHeader
Exact content of the HTTP accept headers as sent to the 3DS Requestor from the Cardholder’s browser. Mandatory for 3DS v2.
[\s\S]{1,2048}
Conditional
customer.browser.language
Value representing the browser language as defined in IETF BCP47. Returned from navigator.language property. Mandatory for 3DS v2.
[\s\S]{1,8}
Conditional
Content
Content
Content
Content
customer.browser.screenHeight
Total height of the Cardholder’s screen in pixels. Value is returned from the screen.height property. Mandatory for 3DS v2.
[\s\S]{1,6}
Conditional
customer.browser.screenWidth
Total width of the cardholder’s screen in pixels. Value is returned from the screen.width property. Mandatory for 3DS v2.
[\s\S]{1,6}
Conditional
customer.browser.timezone
Time-zone offset in minutes between UTC and the Cardholder browser local time. Note that the offset is positive if the local time zone is behind UTC and negative if it is ahead Mandatory for 3DS v2.
[\s\S]{1,5}
Conditional
customer.browser.userAgent
Exact content of the HTTP user-agent header. Mandatory for 3DS v2.
[\s\S]{1,2048}
Conditional
customer.browser.javaEnabled
Boolean that represents the ability of the cardholder browser to execute Java. Value is returned from the navigator.javaEnabled property. Mandatory for 3DS v2.
true/false
Conditional
customer.browser.screenColorDepth
Value representing the bit depth of the colour palette for displaying images, in bits per pixel. Obtained from Cardholder browser using the screen.colorDepth property.
N2 [0-9]{1,2}
Optional
customer.browser.challengeWindow
Dimensions of the challenge window that has been displayed to the Cardholder. The ACS shall reply with content that is formatted to appropriately render in this window to provide the best possible user experience. Preconfigured sizes are width x height in pixels of the window displayed in the Cardholder browser window.
N2
Optional
customer.browser.deviceId
Value representing the customer browser device id.
AN32 [\s\S]{1,32}
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.* and shipping.customer.browser.deviceId
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 Mandatory for 3D Secure v2.
AN100 [\s\S]{1,100}
Conditional
billing.street2
The adjoining road or locality (if required) of the billing address The combination of billing.street1 and billing.street2 can't contain numbers only, it should also include characters.
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 Mandatory for 3D Secure v2.
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 Mandatory for 3D Secure v2.
AN30 [A-Za-z0-9]{1,30}
Conditional
billing.country
A2 [A-Z]{2}
Conditional
billing.normalized
The normalized shipping address.
AN255 [\s\S]{1,255}
Optional
billing.validationStatus
Indicates whether a address got validated and normalized address got confirmed by the consumer
AN255 [\s\S]{1,255}
Optional
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.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.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, PUDO, EXPEDITED
AN30 [A-Z_]{5,30}
Conditional
shipping.cost
The total amount of the shipping costs.
N13 [0-9]{1,10}\.[0-9]{2}
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
shipping.returnTrackingNumber
The tracking number issued for returns
AN255 [\s\S]{1,255}
Optional
shipping.normalized
The normalized shipping address.
AN255 [\s\S]{1,255}
Optional
shipping.validationStatus
Indicates whether a address got validated and normalized address got confirmed by the consumer
AN255 [\s\S]{1,255}
Optional
shipping.warehouse
The warehouse that fulfilled the order
AN100 [\s\S]{1,100}
Optional
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
merchant.data[key]
The additional data received from merchant alongside with transaction data.
key: AN64 [a-zA-Z0-9\._]{3,64} value: AN2048 [\s\S]{0,2048}
Optional
merchant.websiteId
The website id of merchant, represents random session id unique for current transaction.
AN255 [\s\S]{0,255}
Optional
Cart
Cart items
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, and maximum 1000. 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,12}(\\.[0-9]{0,3})
Conditional
cart.items[n].type
The type of the purchased item in the shopping cart. Values can be: PHYSICAL, DIGITAL, MIXED, ANONYMOUS_DONATION, AUTHORITIES_PAYMENT
AN255 [\s\S]{1,255}
Conditional
cart.items[n].sku
The sku cart item.
AN255 [\s\S]{1,255}
Optional
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].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].totalAmount
The total amount of the cart item including quantity.
N13 [0-9]{1,10}\.[0-9]{2}
Conditional
cart.items[n].taxAmount
The tax amount of the cart item. The item's tax amount is independent of the quantity.
N13 [0-9]{1,10}\.[0-9]{2}
Conditional
cart.items[n].totalTaxAmount
The total tax amount of the cart item.
N13 [0-9]{1,10}\.[0-9]{2}
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
cart.items[n].quantityUnit
The cart item's unit of quanity.
M, CM, KG, G, COUNT (default)
Optional
cart.items[n].productUrl
The cart item's URL.
Valid URL
Optional
cart.items[n].imageUrl
The cart item's image URL.
Valid URL
Optional
cart.items[n].totalDiscountAmount
The cart item's total discount amount. The total discount amount is related to the discount percentage
N10.N2[0-9]{1,10}\.[0-9]{2}
Optional
Cart payments
The cart payments data structure holds information about already made payments associated with the cart. The cart payments are counted up by changing the index-number [n], starting with 0. Example: cart.payments[0].name=First Cart Item
Parameter
Description
Format
Required
cart.payments[n].name
The name of the payment methtod. Example: cart.payments[0].name=promotion giftcard 50
AN255 [\s\S]{1,255}
Optional
cart.payments[n].type
The type of the used payment. One of the options: GIFTCARD, PROMOTION Example: cart.payments[0].type=GIFTCARD
AN255 [\s\S]{1,255}
Optional
cart.payments[n].amount
The amount of the associated and already used payment method. Example: cart.payments[0].amount=10.90
N10.N2 [0-9]{1,10}\.[0-9]{2}
Optional
cart.payments[n].currency
The currency of the already used payment amount. Example: cart.payments[0].currency=EUR
A3 [a-zA-Z]{3}
Optional
cart.payments[n].status
The status of the already used payment method. One of the options: pending, authorized, captured Example: cart.payments[0].status=captured
AN255 [\s\S]{1,255}
Optional
cart.payments[n].brand
The brand of the already used payment method, eg. SVS Example: cart.payments[0].name=SVS
AN255 [\s\S]{1,255}
Optional
cart.payments[n].primary
Identifies this payment method being the primary payment method used for that cart. One of the options: true, false Example: cart.payments[0].primary=false
true|false
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 system. 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 PrimeiroPay 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.
AN128 [\s\S]{1,128}
Conditional
recurringMigration.connectorTxId2
Indicates INITIAL payment response details as received from the acquirer.
AN128 [\s\S]{1,128}
Conditional
recurringMigration.connectorTxId3
Indicates INITIAL payment response details as received from the acquirer.
AN128 [\s\S]{1,128}
Conditional
3D Secure
The 3D secure data structure is used to hold authentication data generated by the 3D secure MPI when an external MPI is being used, or additional information about the authentication. If 3D data is present which indicates the usage of an external MPI (xid, eci, verificationId), the payment gateway will just pass through these values to the acquiring system. For more detailed information about the required fields for 3D Secure version 2.0 and above, please visit the 3D Secure 2.0 guide here
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
threeDSecure.enrollmentStatus
The enrollment status for the 3D secure request. Required when using a third-party MPI.
AN1 [YUN]
Conditional
threeDSecure.authenticationStatus
The authentication status for the 3D secure request. Required when using a third-party MPI.
AN1 [YAUN]
Conditional
threeDSecure.merchant.name
Merchant name as defined by the Scheme Directory Server.
AN100 [\s\S]{100}
Optional
threeDSecure.merchant.url
Merchant URL
AN2048 [\s\S]{0,2048}
Optional
threeDSecure.merchant.country
Merchant country
AN3 A3 [A-Za-z]{3}
Optional
threeDSecure.v1.visa.requestorId
Merchant ID for 3D Secure version 1.0, assigned by Visa.
AN100 [\s\S]{100}
Optional
threeDSecure.v1.mastercard.requestorId
Merchant ID for 3D Secure version 1.0, assigned by Mastercard.
AN100 [\s\S]{100}
Optional
threeDSecure.v1.diners.requestorId
Merchant ID for 3D Secure version 1.0, assigned by Diners/Discover.
AN100 [\s\S]{100}
Optional
threeDSecure.v1.diners.password
Password for the Diners/Discover ProtectBuy Directory Server. Used for 3D Secure 1.0
AN100 [\s\S]{100}
Optional
threeDSecure.v1.amex.requestorId
Merchant ID for 3D Secure version 1.0, assigned by American Express.
AN100 [\s\S]{100}
Optional
threeDSecure.v1.jcb.requestorId
Merchant ID for 3D Secure version 1.0, assigned by JCB.
AN100 [\s\S]{100}
Optional
threeDSecure.v1.jcb.password
Password for the JCB J/Secure Directory Server. Used for 3D Secure 1.0
AN100 [\s\S]{100}
Optional
threeDSecure.v1.dankort.requestorId
Merchant ID for 3D Secure version 1.0, assigned by Dankort.
AN100 [\s\S]{100}
Optional
threeDSecure.v1.bcmc.requestorId
Merchant ID for 3D Secure version 1.0, assigned by Bancontact/Mistercash.
AN100 [\s\S]{100}
Optional
threeDSecure.v2.visa.requestorId
Requestor ID for 3D Secure version 2, assigned by Visa.
AN100 [\s\S]{100}
Optional
threeDSecure.v2.visa.requestorName
Requestor Name for 3D Secure version 2, assigned by Visa.
AN100 [\s\S]{100}
Optional
threeDSecure.v2.mastercard.requestorId
Requestor ID for 3D Secure version 2, assigned by Mastercard.
AN100 [\s\S]{100}
Optional
threeDSecure.v2.mastercard.requestorName
Requestor Name for 3D Secure version 2, assigned by Mastercard.
AN100 [\s\S]{100}
Optional
threeDSecure.v2.amex.requestorId
Requestor ID for 3D Secure version 2, assigned by American Express.
AN100 [\s\S]{100}
Optional
threeDSecure.v2.amex.requestorName
Requestor Name for 3D Secure version 2, assigned by American Express.
AN100 [\s\S]{100}
Optional
threeDSecure.v2.diners.requestorId
Requestor ID for 3D Secure version 2, assigned by Diners/Discover.
AN100 [\s\S]{100}
Optional
threeDSecure.v2.diners.requestorName
Requestor Name for 3D Secure version 2, assigned by Diners/Discover.
AN100 [\s\S]{100}
Optional
threeDSecure.v2.jcb.requestorId
Requestor ID for 3D Secure version 2, assigned by JCB.
AN100 [\s\S]{100}
Optional
threeDSecure.v2.jcb.requestorName
Requestor Name for 3D Secure version 2, assigned by JCB.
AN100 [\s\S]{100}
Optional
threeDSecure.v2.cartebancaire.requestorId
Requestor ID for 3D Secure version 2, assigned by Carte Bancaire.
AN100 [\s\S]{100}
Optional
threeDSecure.v2.cartebancaire.requestorName
Requestor Name for 3D Secure version 2, assigned by Carte Bancaire.
AN100 [\s\S]{100}
Optional
threeDSecure.dsTransactionId
Transaction ID assigned by the directory server. Used when the transaction was already authenticated via 3D Secure version 2, using an external MPI.
AN100 [\s\S]{36}
Optional
threeDSecure.version
Version of the 3D Secure that was used when the transaction was already authenticated using an external MPI. For example: 1.0.2 or 2.1.0
(1|2)\.[0-9]\.[0-9]
Optional
threeDSecure.challengeIndicator
Indicates whether a challenge is requested for this transaction. Can be sent when 3D Secure version 2.2 or higher is used.
0[1-9]
Optional
threeDSecure.challengeMandatedIndicator
Indication of whether a challenge is required for the transaction to be authorized due to local/regional mandates or other variable. Can be used when the transaction was authenticated via an external MPI.
AN1 (Y|N)
Optional
threeDSecure.authType
The type of authentication that was requested by the ACS. Can be used when the transaction was authenticated via an external MPI.
AN2 0[1-4]
Optional
threeDSecure.exemptionFlag
Flags the transaction as exemption during authorization. Can be used for 3D Secure version 2.2 or higher.
N2 0[1-4]
Optional
threeDSecure.transactionStatusReason
Provides information on why the Transaction Status field has the specified value. Can be used when the transaction was authenticated via an external MPI.
N2
Optional
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 PrimeiroPay) 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