API Parameters Reference
This reference section provides you with a complete and in-depth description of the PrimeiroPayment Platform API.
- Test: https://test.oppwa.com/
- Live: https://oppwa.com/
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 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:
Show throttling details
Show throttling details
Requests which will be affected by throttling, will be rejected with following return code:
{
"buildNumber":"[email protected] 06:31:46 +****",
"id":"8ac9a4a8658afc790165a3f0e436198d",
"ndc":"8acda4c9635ea2d90163636f0a462510_ebb07f3e26e942908d6eeed03a813237",
"result":{
"code":"800.120.100",
"description":"Too many requests. Please try again later."
},
"timestamp":"2018-09-04 09:42:33+0000"
}
The API version is indicated in the request URL e.g. /v1/payments indicates version 1.
All changes made to the API are backwards compatible, hence any major features that are released, that would otherwise break existing implementations, will be released using a new version.
Our system expects data to be sent encoded in UTF-8.
Using this Content-Type header can help:
application/x-www-form-urlencoded; charset=UTF-8
For each request you send to our API the
HTTP status code of the response will already tell you the basic result.200 - successful request
307 - temporary redirect
400 - bad request. This might either point to e.g. invalid parameters or values sent. It's also returned if the payment failed e.g. because the acquirer declined.
401 - invalid authorization header provided
403 - invalid access token provided
404 - requested resource or endpoint is not found. I.e. endpoint/url doesn't exist. This can also be caused by typos like POST /v1/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.
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 behaviourBrand | 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 |
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.
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 |
currency | A3 [A-Z]{3} | Required | |
paymentBrand | The brand specifies the method of payment for the request. This is optional if you want to use brand detection for credit cards, if not then it is mandatory. | AN32 [a-zA-Z0-9_] {1,32} | Conditional |
paymentType | The payment type for the request. You can send payment requests with one of the following types:
| 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:
| AN32 [a-zA-Z0-9]{0,32} | Optional |
To make REST API calls, include the access token in the Authorization header with the Bearer authentication scheme.
Parameter / Header | Description | Format | Required |
entityId | The entity 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 |
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 |
There are two possible APIs for Apple Pay:
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 |
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 |
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 |
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 | 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 |
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 |
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 |
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 |
The shipping address holds the location and recipient of ordered goods. This can be used for risk processing or logistics.
Parameter | Description | Format | Required |
shipping.street1 | The door number, floor, building number, building name, and/or street name of the shipping address | AN100 [\s\S]{1,100} | Conditional |
shipping.street2 | The adjoining road or locality (if required) of the shipping address | AN100 [\s\S]{1,100} | Conditional |
shipping.houseNumber1 | Primary house number (door number or building number) of the shipping address. If present, then shipping.street1 is assumed to contain only the name of the street. Also, shipping.street2 will be ignored. | AN100 [\s\S]{1,100} | Optional |
shipping.houseNumber2 | Secondary house number of the shipping address (floor, building name). Used when more addresses are bundled to a same primary house number. If present, shipping.houseNumber1 is also mandatory. | AN100 [\s\S]{1,100} | Optional |
shipping.city | The town, district or city of the shipping address | AN80 [a-zA-Z]{1,80} | Conditional |
shipping.state | The county, state or region of the shipping address | AN50 [a-zA-Z0-9\.]{1,50} | Conditional |
shipping.postcode | The postal code or zip code of the shipping address | AN30 [A-Za-z0-9]{1,30} | Conditional |
shipping.country | A2 [A-Za-z]{2} | Conditional | |
shipping.method | Method of the shipping. One of the options: LOWEST_COST, CARRIER_DESIGNATED_BY_CUSTOMER, ELECTRONIC_DELIVERY, GROUND, INTERNATIONAL, MILITARY, NEXT_DAY_OVERNIGHT, OTHER, STORE_PICKUP, SAME_DAY_SERVICE, TWO_DAY_SERVICE, THREE_DAY_SERVICE, 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 |
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 |
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 |