Introduction

This reference section describes the APIs for Server-to-Server, Mobile SDK, and COPYandPAY.

Hosts

Live: https://card.peachpayments.com/
Sandbox: https://sandbox-card.peachpayments.com/

Authentication

Send all requests over SSL.
Authenticate all requests against an Authorization Bearer header with an access token. Send all other data parameters as body parameters (see Authentication parameters for more information).

Throttling

Throttling limits the number of requests submitted to an API in a given amount of time. This protects the web service from too much traffic and ensures a healthy service.

Operation	Endpoint	Max requests	Time unit
COPYandPAY - Get payment status	`GET /v1/checkouts/{checkoutId}/payment`	9*	minute
COPYandPAY - Update checkout	`GET /v1/checkouts/{checkoutId}`	200	minute
Server-to-Server - Get payment status	`GET /v1/payments/{paymentId}`	2	minute
Server-to-Server - Partial Backoffice operations	`GET /v1/payments/{paymentId}`	200	minute
Server-to-Server - Payments over a token	`POST /v1/registrations/{registrationId}/payments`	200	minute
Reporting - Transaction search (paymentId)	`GET /v1/query/{paymentId}/`	2	minute
Reporting - Transaction search (merchantTransactionId)	`GET /v1/query/`	2	minute
Secure query - Query secure payment token	`GET /v1/secureRegistrations/{registrationId}`	100	hour
Reporting - Transaction search (paymentId)	`GET /v3/query/{paymentId}/`	100	minute
Reporting - Transaction search (merchantTransactionId)	`GET /v3/query/`	30	minute

* On sandbox, the max requests for GET /v1/checkouts/{checkoutId}/payment is two per minute.

The APIs reject requests affected by throttling with the following return code:

{
  "buildNumber": "b297e8ec4aa0888454578e292c67546d4c6a5c28@2018-08-30 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"
}

Versioning

The request URL includes the API version (for example, /v1/payments indicates version 1). All changes made to the API are backwards compatible. Peach Payments releases new versions for any major features that would break existing implementations.

Encoding

The Peach Payments system expects you to send data encoded in UTF-8. Using the application/x-www-form-urlencoded; charset=UTF-8 content type header can help.

HTTP status codes

For each request you send, the HTTP status code of the response indicates the basic result:

200: OK
307: Temporary redirect
400: Bad request (request failed due to missing or invalid parameters. Also returned if the payment failed, for example, if the acquirer declined the transaction)
401: Unauthorised
403: Forbidden (authentication details are valid but do not provide enough permissions to access the requested resource)
404: Not found (cannot find the requested resource or endpoint, that is, the endpoint or URL does not exist (for example, POST /v1/paymnets instead of payments); typos or wrong IDs can also cause this (for example, GET /v1/payments/{id} where no payment with {id} exists))

For payments, you can get more detailed information in the Response codes section to find out why a payment failed.

HTTP response body

The HTTP response body is in JSON format. Process the HTTP response and be aware that Peach Payments can add new fields to the JSON structure at any time.

{
  "id": "8ac7a4a289d210fc0189d5b4e9572cc8",
  "paymentType": "DB",
  "paymentBrand": "VISA",
  "amount": "92.00",
  "currency": "EUR",
  "descriptor": "7766.2840.5126 OPP_Channel ",
  "result": {
    "code": "000.100.110",
    "description": "Request successfully processed in 'Merchant in Integrator Test Mode'"
  },
  "resultDetails": {
    "ExtendedDescription": "Authorized",
    "clearingInstituteName": "Your Clearing Institute Name",
    "ConnectorTxID1": "00000000776628405126",
    "ConnectorTxID3": "0170|085",
    "ConnectorTxID2": "012416",
    "AcquirerResponse": "0000"
  },
  "card": {
    "bin": "420000",
    "last4Digits": "0000",
    "holder": "Jane Jones",
    "expiryMonth": "05",
    "expiryYear": "2034"
  },
  "risk": {
    "score": "100"
  },
  "buildNumber": "5ce30a257f96b238fa8ecc669ffdc2a77040ba35@2023-08-08 07:36:04 +0000",
  "timestamp": "2023-08-08 15:12:30.752+0000",
  "ndc": "8a8294174b7ecb28014b9699220015ca_83281e556b1e4216bef5c3bc1f63c45c"
}

Testing

Two test modes are available:

testMode=EXTERNAL: Forwards test transactions to the processor's test system for end-to-end testing.
testMode=INTERNAL: Sends transactions to Peach Payments simulators (default if you don't send the testMode parameter).

🚧
The testMode parameter is only supported in the test environment. Peach Payments declines any requests that you send to the production environment with the testMode parameter with the 600.200.701 - testMode not allowed on production error message.

Credit card test accounts

Brand	Number	CVV	Expiry date
Visa	4200000000000000 (no 3-D)	any 3 digits	any future date
	4711100000000000 (3-D enrolled)	any 3 digits	any future date
Mastercard	5454545454545454 (no 3-D)	any 3 digits	any future date
	5212345678901234 (3-D enrolled)	any 3 digits	any future date
American Express	377777777777770 (no 3-D)	any 4 digits	any future date
	375987000000005 (3-D enrolled)	any 4 digits	any future date

Test bank accounts

Test bank accounts for the Single Euro Payments Area (SEPA):

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

Basic payment

Parameter	Description	Format	Condition
`amount`	Indicates the amount of the payment request. The dot is the decimal separator. The amount is the only value that 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
`currency`	The currency code of the payment request's amount (ISO 4217).	A3 `[A-Z]{3}`	Required
`paymentType`	The payment type for the request. Supported types: - PA (preauthorisation): Stand-alone authorisation that can trigger optional risk management and validation. A capture (CP) with reference to the (PA) confirms the payment. - DB (debit): Debits the customer's account and credits the merchant account. - CD (credit): Credits the customer's account and debits the merchants account. - CP (capture): Captures a preauthorised amount. - RV (reversal): Reverses an already processed PA, DB, or CD transaction. As a consequence, the end customer never sees any booking on their statement. Reversals are not always supported. - RF (refund): Credits a prior debit or credit. Refunds are not always supported.	A2	Required
`taxAmount`	Indicates the tax amount of the payment request. The dot is the decimal separator.	N10.N2 `[0-9]{1,10}(\.[0-9]{2})?`	Conditional
`paymentBrand`	Specifies the method of payment for the request. Optional if using brand detection for credit cards; otherwise, it is mandatory.	AN32 `[a-zA-Z0-9_]{1,32}`	Conditional
`merchantTransactionId`	Merchant-provided unique reference number for transactions. Required by some receivers and used for reconciliation.	AN255 `[\s\S]{8,255}`	Conditional
`discountAmount`	L3 card data invoice level discount amount.	N10.N2 `[0-9]{1,10}(\.[0-9]{2})?`	Optional
`integrity`	If true, Peach Payments calculates the SRI hash of the payment and returns it in the response. Needed for compliance with PCI requirements.	A5 true\|false	Optional
`overridePaymentType[brand]`	Overrides the default payment type for specific brands. Example: `overridePaymentType[BOLETO]=PA`. In this case, the default payment type is the one defined in `paymentType` parameter and every brand defined in `overridePaymentType` has its own payment type. This parameter is only accepted during checkout creation.	brand: AN32 `[a-zA-Z0-9_]{1,32}` value: A2	Optional
`descriptor`	Can populate all or part of the merchant name descriptor, often appearing on the shopper's statement. Full use depends on merchant account configuration. `merchant.name` can override any data sent in this field.	AN127 `[\s\S]{1,127}`	Optional
`merchantInvoiceId`	Merchant-provided unique invoice number for transactions. Not sent onwards.	AN255 `[\s\S]{8,255}`	Optional
`merchantMemo`	Merchant-provided extra information. Appears in reporting but is not transaction-processing relevant.	AN255 `[\s\S]{8,255}`	Optional
`transactionCategory`	Category of the transaction. Possible values: - EC: eCommerce - MO: Mail order - TO: Telephone order - PO: POS - PM: mPOS - MOTO: Mail order telephone order.	AN32 `[a-zA-Z0-9]{0,32}`	Optional
`sequence`	Field to highlight the last transaction for `CP`, `RV`, `RF`, and so on. Example: `sequence=FINAL` indicates this is the last transaction.	AN	Optional
`numberOfCaptures`	Sets the maximum number of possible partial captures.	N2 `[1-9]\|[1-8][0-9]\|9[0-8]`	Optional
`promotionCode`	Discount code applied at the order level. One promotion code per order.	AN15 `[A-Za-z0-9]{0,15}`	Optional
`locale`	Sets the language/country. Example: `de-AT`, `en-US`. Check connector requirements to ensure supported languages/countries.	AN10 `[\s\S]{1,10}`	Optional
`transactionLinkId`	Transaction link identifier used by Mastercard to promote consistent linking of life cycle activity.	AN35 `[\s\S]{1,35}`	Optional
`transactionPurposeCode`	Transaction purpose code.	AN12 `[\s\S]{1,12}`	Optional
`integrationType`	Integration type.	AN10 `[\s\S]{1,10}`	Optional

Forex

Parameter	Description	Format	Condition
`forex.amount`	The amount of the request which Peach Payments could use when there is a process of changing one currency into another during the transaction.	N10.N2 `[0-9]{1,10}(\.[0-9]{2})?`	Conditional
`forex.currency`	ISO 4217 alphabetical currency code which Peach Payments could use when there is a process of changing one currency into another during the transaction.	A3 `[A-Z]{3}`	Conditional

Authentication

To make REST API calls, include the access token in the authorisation header with the bearer authentication scheme.

Parameter	Description	Format	Condition
`Authorisation Bearer <access-token>`	Authorisation header with bearer authentication scheme. Retrieve the access token from the Dashboard.	Header	Required
`entityId`	The entity required to authorise the request. This should be the channel entity identifier. If channel dispatching is active, it should be the merchant entity identifier.	AN32 `[a-f0-9]{32}`	Conditional

Card account

The card data structure holds all information for credit or debit card accounts.

Parameter	Description	Format	Condition
`card.number`	The card's PAN or account number.	N32 `[0-9]{8,32}`	Required
`card.expiryMonth`	The card's expiry month.	N2 `(0[1-9]\|1[0-2])`	Required
`card.expiryYear`	The card's expiry year.	N4 `(19\|20)([0-9]{2})`	Required
`card.cvv`	The card's security code or CVV.	N4 `[0-9]{3,4}`	Conditional
`card.holder`	Credit card account holder.	A128 `{3,128}`	Optional

Apple Pay

Encrypted payment token

You can send the encrypted payment token as-is. Peach Payments performs the decryption and processes the transaction.

Parameter	Description	Format	Condition
`applePay.paymentToken`	The encrypted payment token created by Apple.	Defined by Apple	Required

Decrypted card information

You can do the decryption and send Peach Payments 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	Condition
`applePay.source`	Indicates the source of Apple Pay.	web\|app	Required

Google Pay

Encrypted payment token

You can send the encrypted payment token as-is. Peach Payments performs the decryption and processes the transaction.

Parameter	Description	Format	Condition
`googlePay.paymentToken`	The encrypted payment token created by Google.	Defined by Google	Required

Decrypted card information

Parameter	Description	Format	Condition
`googlePay.source`	Indicates the source of Google Pay.	web\|app	Required

Virtual account

Use the virtual account data structure to send account-based payments, for example, PayPal.

Parameter	Description	Format	Condition
`virtualAccount.accountId`	The shopper's virtual account identifier.	AN100 `[\s\S]{1,100}`	Required

Bank account

The bank account data structure holds all the information that specifies a bank account. Peach Payments uses it for bank-account-based payments, for example, direct debits, SEPA, and bank transfers. Collecting money from the shopper's bank account generally requires their approval. SEPA-specific parameters like bankAccount.mandate.id, bankAccount.mandate.dateOfSignature, and transactionDueDate are not used in the risk checks.

Parameter	Description	Format	Condition
`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. You must provide either the `number` or the `iban`.	AN64 `[a-zA-Z0-9]{3,64}`	Conditional
`bankAccount.iban`	The IBAN (International Bank Account Number) associated with the bank account.	AN31 `[a-zA-Z]{2}[0-9]{2}[a-zA-Z0-9]{11,27}`	Conditional
`bankAccount.bankCode`	The code associated with the bank account. You must provide either the `bankCode` or the `bic`.	AN12 `[a-zA-Z0-9]{1,12}`	Conditional
`bankAccount.bic`	The BIC (Bank Identifier Code (SWIFT)) number of the bank account. You must provide either the `bankCode` or the `bic`.	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 signing date of the direct debit mandate.	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

Token account

Use the token account data structure to send token-based payments towards the acquirer.

Parameter	Description	Format	Condition
`tokenAccount.number`	The encrypted payment token created by the external provider.	N19 `[0-9]{12,19}`	Required
`tokenAccount.type`	The token account type. Possible values: (1) `EXTERNAL` (acquirer or external provider token), (2) `NETWORK` (scheme provider token)	EXTERNAL \| NETWORK	Required
`tokenAccount.expiryMonth`	The token's expiry month.	N2 `(0[1-9]\|1[0-2])`	Optional
`tokenAccount.expiryYear`	The token's expiry year.	N4 `(19\|20)([0-9]{2})`	Optional
`tokenAccount.cryptogram`	Dynamic data generated using EMV-based cryptography to secure the transaction. Must be `base64` encoded.	AN32 `[\s\S]{28,32}`	Conditional
`tokenAccount.dtvc`	Dynamic token verification code (dynamic one-time CVC2 generated for a token).	N4 `[0-9]{3,4}`	Conditional

Customer

The customer data structure holds information about the customer such as their name, identification documents, and contact details. The customer fields serve mixed purposes: to store information on your customers and for risk management and payment providers that require ID or mandate information.

Parameter	Description	Format	Condition
`customer.givenName`	The first name of the customer. Required if you provide any other customer parameters. Max 50 characters.	AN50 `[\s\S]`	Conditional
`customer.surname`	The last name of the customer. Required if you provide any other customer parameters. Max 50 characters.	AN50 `[\s\S]`	Conditional
`customer.identificationDocType`	Identification document type: `IDCARD`, `PASSPORT`, `TAXSTATEMENT`.	A12 `[\s\S]`	Conditional
`customer.identificationDocId`	ID of the identification document. Required if you provide `identificationDocType`.	AN64 `[\s\S]{8,64}`	Conditional
`customer.browser.acceptHeader`	Content of the HTTP accept headers. Required for 3-D Secure v2.	`[\s\S]{1,2048}`	Conditional
`customer.browser.language`	Browser language as defined in IETF BCP47. Required for 3-D Secure v2.	`[\s\S]{1,8}`	Conditional
`customer.browser.screenHeight`	Total height of the shopper's screen in pixels. Required for 3-D Secure v2.	`[\s\S]{1,6}`	Conditional
`customer.browser.screenWidth`	Total width of the shopper's screen in pixels. Required for 3-D Secure v2.	`[\s\S]{1,6}`	Conditional
`customer.browser.timezone`	Time-zone offset between UTC and the local time in minutes. Required for 3-D Secure v2.	`[\s\S]{1,5}`	Conditional
`customer.browser.userAgent`	Content of the HTTP user-agent header. Required for 3-D Secure v2.	`[\s\S]{1,2048}`	Conditional
`customer.browser.javaEnabled`	Boolean indicating whether the shopper's browser has Java enabled. Required for 3-D Secure v2.	true\|false	Conditional
`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.middleName`	The middle name of the customer. Max 50 characters.	AN50 `[\s\S]{2,50}`	Optional
`customer.sex`	Sex of the shopper: M for male, F for female	A1 M\|F	Optional
`customer.birthDate`	Customer's birth date in the format `yyyy-MM-dd`, for example, 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`	Customer's phone number. Required for some risk checks.	AN25 `[+0-9][0-9 \.()/-]{0,25}`	Optional
`customer.mobile`	Customer's mobile number. Required for some risk checks.	AN25 `[+0-9][0-9 \.()/-]{0,25}`	Optional
`customer.workPhone`	Customer's work phone number. Required for some risk checks.	AN25 `[\s\S]{1,25}`	Optional
`customer.email`	Customer's email address. Required for some risk checks and direct debit mandate transmission.	AN128 `[\s\S]{6,128}`	Optional
`customer.companyName`	Customer's company name.	AN60 `[\s\S]{1,60}`	Optional
`customer.ip`	Customer's IP address.	AN255 `[\s\S]{1,255}`	Optional
`customer.merchantReference`	Reference information for the payee.	AN255 `[\s\S]`	Optional
`customer.salutation`	Valid options: `MR`, `MRS`, `MS`, `MX`.	A3 `[\s\S]`	Optional
`customer.language`	Customer's language (for example, `NO`, `DE`).	[A-Z] `{2}`	Optional
`customer.category`	Customer type: `INDIVIDUAL`, `COMPANY`.	A10 `[\s\S]`	Optional
`customer.browserFingerprint.id`	Reference to the browser fingerprint.	[\s\S]`{1,255}`	Optional
`customer.browserFingerprint.value`	Actual value of the browser fingerprint.	[\s\S]`{1,4096}`	Optional
`customer.browser.screenColorDepth`	Bit depth of the colour palette for displaying images.	N2 `[0-9]{1,2}`	Optional
`customer.browser.challengeWindow`	Dimensions of the challenge window displayed to the shopper.	N1	Optional
`customer.browser.deviceId`	Device ID of the shopper's browser.	AN32 `[\s\S]{1,32}`	Optional
`customer.app.deviceId`	Device ID of the shopper's mobile device.	AN40 `[\s\S]{1,40}`	Optional
`customer.status`	Status of the customer: `NEW`, `EXISTING`.	A9 `[\s\S]{1,255}`	Optional

Shipping customer

The shipping customer has the same fields than the billing customer, but as part of the shipping entity. That way you can ship to an entirely different customer.

Parameter	Description	Format	Condition
`shipping.customer.`*	All the parameters that are available under customer except `shipping.customer.browserFingerprint.`*, `shipping.customer.browser.deviceId`, and `shipping.customer.app.deviceId`.	Same as customer fields	Optional

Billing address

The billing address holds the address of the customer. You can use the information sent in the billing address data structure for risk checks such as AVS for card processing.

Parameter	Description	Format	Condition
`billing.street1`	The door number, floor, building number, building name, and street name of the billing address. Mandatory for 3-D 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` cannot contain only numbers; it should also include characters.	AN100 `[\s\S]{1,100}`	Conditional
`billing.city`	The town, district, or city of the billing address. Mandatory for 3-D Secure v2.	AN48 `[\s\S]{1,48}`	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 3-D Secure v2.	AN16 `[A-Za-z0-9]{1,16}`	Conditional
`billing.country`	The country of the billing address, represented using the ISO 3166-1 standard. Mandatory for 3-D Secure v2.	A2 `[A-Z]{2}`	Conditional
`billing.houseNumber1`	Primary house number (door number or building number) of the billing address. If present, Peach Payments assumes `billing.street1` only contains the name of the street and ignores `billing.street2`.	AN100 `[\s\S]{1,100}`	Optional
`billing.houseNumber2`	Secondary house number (floor, building name) of the billing address. Used when you bundle more addresses to the same primary house number. If present, `billing.houseNumber1` is also mandatory.	AN100 `[\s\S]{1,100}`	Optional
`billing.normalized`	The normalised billing address.	AN255 `[\s\S]{1,255}`	Optional
`billing.validationStatus`	Indicates whether Peach Payments validated an address and whether the customer confirmed the normalised address.	AN255 `[\s\S]{1,255}`	Optional

Merchant billing address

The merchant billing address has the same fields as the billing address with more parameters. This allows billing from an entirely different merchant location.

Parameter	Description	Format	Condition
`merchant.billing.*`	All the fields that are available under the billing address.	Same as for billing address fields	Optional
`merchant.billing.givenName`	The first name or given name of the merchant.	AN `[\s\S]`	Optional
`merchant.billing.surname`	The last name or surname of the merchant.	AN `[\s\S]`	Optional
`merchant.billing.middleName`	The middle name of the merchant.	AN `[\s\S]`	Optional
`merchant.billing.companyName`	The merchant's company name.	AN60 `[\s\S]{1,60}`	Optional
`merchant.billing.phone`	The merchant's phone number.	AN25 `[\s\S]{1,25}`	Optional
`merchant.billing.workPhone`	The merchant's work phone number.	AN25 `[\s\S]{1,25}`	Optional
`merchant.billing.mobile`	The merchant's mobile number.	AN25 `[+0-9][0-9 \.()/-]{5,25}`	Optional
`merchant.billing.email`	The merchant's email address.	AN128 `[\s\S]{6,128}`	Optional

Shipping address

The shipping address holds the location and recipient of ordered goods. You can use this for risk processing or logistics.

Parameter	Description	Format	Condition
`shipping.street1`	The door number, floor, building number, building name, and 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.	AN16 `[A-Za-z0-9]{1,16}`	Conditional
`shipping.country`	The country of the shipping address (ISO 3166-1).	A2 `[A-Za-z]{2}`	Conditional
`shipping.method`	Method of the shipping. Possible values: `CARRIER_DESIGNATED_BY_CUSTOMER`, `ELECTRONIC_DELIVERY`, `EXPEDITED`, `GROUND`, `INTERNATIONAL`, `LOWEST_COST`, `MILITARY`, `NEXT_DAY_OVERNIGHT`, `OTHER`, `POINT_PICKUP`, `PUDO`, `SAME_DAY_SERVICE`, `STORE_PICKUP`, `THREE_DAY_SERVICE`, `TWO_DAY_SERVICE`.	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.houseNumber1`	Primary house number (door number or building number) of the shipping address. If you provide this, then `shipping.street1` must contain only the name of the street. Also, the system ignores `shipping.street2`.	AN100 `[\s\S]{1,100}`	Optional
`shipping.houseNumber2`	Secondary house number of the shipping address (floor, building name). Use this when bundling more addresses to the same primary house number. If you provide this, then you must also provide `shipping.houseNumber1`.	AN100 `[\s\S]{1,100}`	Optional
`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 system provides the normalised shipping address.	AN255 `[\s\S]{1,255}`	Optional
`shipping.validationStatus`	This indicates whether the system validated the address and confirmed the normalised address with the consumer.	AN255 `[\s\S]{1,255}`	Optional
`shipping.warehouse`	The warehouse that fulfilled the order.	AN100 `[\s\S]{1,100}`	Optional
`shipping.preference`	This indicates the shipping preference. Possible values: `GET_FROM_FILE` (use the shipping address provided by the customer at acquirer-hosted pages), `NO_SHIPPING` (no shipping expected for the purchase), `SET_PROVIDED_ADDRESS` (use the merchant-provided address). Default value: `GET_FROM_FILE`.	AN21 GET_FROM_FILE\|NO_SHIPPING\|SET_PROVIDED_ADDRESS	Optional
`shipping.middleName`	The middle name for the shipping address.	AN `[\s\S]`	Optional
`shipping.companyName`	The company name for the shipping address.	AN60 `[\s\S]{1,60}`	Optional
`shipping.phone`	The phone number for the shipping address.	AN25 `[+0-9][0-9 \.()/-]{5,25}`	Optional
`shipping.workPhone`	The work phone number for the shipping address.	AN25 `[\s\S]{1,25}`	Optional
`shipping.mobile`	The mobile number for the shipping address.	AN25 `[+0-9][0-9 \.()/-]{5,25}`	Optional
`shipping.email`	The email address for the shipping address.	AN128 `[\s\S]{6,128}`	Optional
`shipping.type`	This defines the shipping type, either `RETURN` or `SHIPMENT`.	AN8 `[\s\S]`	Optional

Merchant shipping address

The merchant shipping address has the same fields as the shipping address, but as part of the merchant entity. This allows you to ship from an entirely different merchant location.

Parameter	Description	Format	Condition
`merchant.shipping.*`	All the fields that are available under the shipping address except `shipping.customer.*`.	Same as for shipping address fields	Optional

Corporate

The corporate data structure holds information about the corporate company for purchases made on behalf of it.

Parameter	Description	Format	Condition
`corporate.name`	The company's name.	AN30 `[\s\S]{1,30}`	Optional
`corporate.description`	The brief description of the company.	AN160 `[\s\S]{1,160}`	Optional
`corporate.street`	The company's address - street.	AN100 `[\s\S]{1,100}`	Optional
`corporate.address`	The company's address - line 2.	AN100 `[\s\S]{1,100}`	Optional
`corporate.city`	The company's address - city.	AN80 `[\s\S]{1,80}`	Optional
`corporate.state`	The company's address - state.	AN50 `[\s\S]{1,50}`	Optional
`corporate.postCode`	The company's address - postal code.	AN16 `[\s\S]{1,16}`	Optional
`corporate.suite`	The company's suite number.	AN30 `[\s\S]{1,30}`	Optional
`corporate.postboxNumber`	The company's post box number.	AN15 `[\s\S]{1,15}`	Optional
`corporate.purchase`	The company's purchase indicator.	A1 Y\|N	Optional
`corporate.phone`	The company's phone number.	N25 `[0-9]{1,25}`	Optional
`corporate.fax`	The company's fax number.	N25 `[0-9]{1,25}`	Optional
`corporate.vatId`	The company's VAT ID.	AN255 `[\s\S]{0,255}`	Optional

Sender

The sender data structure holds information about the sender (the person who pays the debt).

Parameter	Description	Format	Condition
`sender.name`	The name of the sender.	AN100 `[A-Za-z0-9\s]{0,100}`	Optional
`sender.givenName`	The first name or given name of the sender.	AN50 `[A-Za-z0-9\s]{0,50}`	Optional
`sender.surname`	The last name or surname of the sender.	AN50 `[A-Za-z0-9\s]{0,50}`	Optional
`sender.birthDate`	The birth day of the sender in the format yyyy-MM-dd, for example, 1970-02-17.	AN10 `([0-9]{4})-(0[1-9]\|1[0-2])-(0[1-9]\|1[0-9]\|2[0-9]\|3[0-1])`	Optional
`sender.accountNumber`	The account number of the sender.	AN32 `[\s\S]{0,32}`	Optional
`sender.street`	The door number, floor, building number, building name, and street name of the sender.	AN100 `[A-Za-z0-9\s]{0,100}`	Optional
`sender.city`	The town, district, or city of the sender.	AN50 `[A-Za-z0-9\s]{0,50}`	Optional
`sender.state`	The county, state, or region of the sender.	AN50 `[A-Za-z0-9\s]{0,50}`	Optional
`sender.country`	The country of the sender.	AN3 `[A-Za-z0-9]{0,3}`	Optional
`sender.accountNumberType`	Indicates the sender account number type.	`OTHER`, `RTN_AND_BANK_ACCOUNT`, `IBAN`, `BAN_AND_BIC`, `CARD_ACCOUNT`	Optional
`sender.sourceOfFunds`	The source of funds of the sender.	N2 01 - Visa Credit, 02 - Visa Debit, 03 - Visa Prepaid, 04 - Cash, 05 - Debit/deposit access accounts other than those linked to a Visa card, 06 - Credit accounts other than those linked to a Visa card	Optional

Recipient

The recipient data structure holds information about the recipient (the person whose debt is being paid off).

Parameter / Header	Description	Format	Condition
`recipient.givenName`	The first name or given name of the recipient.	AN48 `[A-Za-z0-9\s]{0,48}`	Optional
`recipient.surname`	The last name or surname of the recipient.	AN48 `[A-Za-z0-9\s]{0,48}`	Optional
`recipient.birthDate`	The birth day of the recipient in the format yyyy-MM-dd, for example, 1970-02-17.	AN10 `([0-9]{4})-(0[1-9]\|1[0-2])-(0[1-9]\|1[0-9]\|2[0-9]\|3[0-1])`	Optional
`recipient.phone`	The phone number of the recipient.	AN25 `[+0-9][0-9 ().-]{7,25}`	Optional
`recipient.accountNumber`	The account number of the recipient.	AN32 `[\s\S]{0,32}`	Optional
`recipient.street`	The door number, floor, building number, building name, and street name of the recipient.	AN100 `[A-Za-z0-9\s]{0,100}`	Optional
`recipient.city`	The town, district, or city of the recipient.	AN50 `[A-Za-z0-9\s]{0,50}`	Optional
`recipient.state`	The county, state, or region of the recipient.	AN50 `[A-Za-z0-9\s]{0,50}`	Optional
`recipient.country`	The country of the recipient.	AN3 `[A-Za-z0-9]{0,3}`	Optional
`recipient.postcode`	The postal code or zip code of the recipient.	AN30 `[\s\S]{1,30}`	Optional
`recipient.accountNumberType`	Indicates the recipient's account number type.	`OTHER`, `RTN_AND_BANK_ACCOUNT`, `IBAN`, `CARD_ACCOUNT`, `EMAIL`, `PHONE_NUMBER`, `BAN_AND_BIC`, `WALLET_ID`, `SOCIAL_NETWORK_ID`	Optional

Merchant

The merchant data structure holds information about you, the merchant (acceptor). Use these fields to override the information shown on the cardholder statement. You can also use them for payment facilitators.

Parameter	Description	Format	Condition
`merchant.name`	The name of the merchant/acceptor. When used, this field overrides the value sent as merchant name and generally makes up the first line of the cardholder statement. Typical usage is in the format `{Merchant DBA Name}*{Description of product or service}`.	AN100	Optional
`merchant.mcc`	The merchant's category code.	AN4	Optional
`merchant.street`	The door number, floor, building number, building name, and street name of the merchant.	AN100	Optional
`merchant.city`	The merchant's city, phone number, or email. This generally makes up the second line of the cardholder statement. For card-present transactions, Peach Payments sends the city of the transaction location. For card-not-present transactions, Peach Payments sends the phone, email, or URL that the shopper would recognise.	AN100	Optional
`merchant.state`	The county, state, or region of the merchant.	AN50	Optional
`merchant.countryCode`	The merchant's three-digit country code as defined in ISO 3166-1.	N3	Optional
`merchant.country`	The merchant's two-letter country code as defined in ISO 3166-1.	A2	Optional
`merchant.postcode`	The postal code or zip code of the merchant.	AN16	Optional
`merchant.geographicCoordinates`	The latitude and longitude of the merchant's location. Example: `61.21630,-149.89500`.	NS20	Optional
`merchant.serviceLocationCity`	The service location city where the cardholder received the services, if it differs from the merchant city name.	AN100	Optional
`merchant.serviceLocationState`	The service location state where the cardholder received the services, if it differs from the merchant country subdivision code.	AN50	Optional
`merchant.serviceLocationCountryCode`	The service location country code where the cardholder received the services, if it differs from the merchant country code.	AN3	Optional
`merchant.serviceLocationPostCode`	The service location postal code where the cardholder received the services, if it differs from the merchant postal code.	AN16	Optional
`merchant.serviceLocationGeographicCoordinates`	The latitude and longitude where the cardholder received the service, if it differs from the merchant's location. Example: `61.21630,-149.89500`.	NS20	Optional
`merchant.additionalContact`	More merchant contact information.	AN255	Optional
`merchant.phone`	The merchant's phone number.	AN25	Optional
`merchant.customerContactPhone`	The merchant's customer service phone number, provided to consumers for customer service purposes.	AN25	Optional
`merchant.websiteId`	The website ID of the merchant, representing a random session ID unique for the current transaction.	AN255	Optional
`merchant.URL`	The merchant's URL address.	AN255	Optional
`merchant.partnerIdCode`	The merchant's partner ID code, representing a partnership agreement, generally between a specific merchant, and issuers.	AN60	Optional
`merchant.isoId`	The merchant's independent sales organisation ID.	AN255	Optional
`merchant.payFacId`	The merchant's payment facilitator ID.	AN255	Optional
`merchant.payFacName`	The merchant's payment facilitator name.	AN255	Optional
`merchant.submerchantId`	Used only for Mastercard Payment Facilitators. The ID of the sub-merchant.	AN100	Optional
`merchant.marketplaceId`	The merchant's marketplace ID.	AN255	Optional
`merchant.taxId`	The merchant's tax ID information.	AN60	Optional
`merchant.data[key]`	Extra data received from the merchant alongside transaction data.	key: AN64 `[a-zA-Z0-9\\._]{3,64}` value: AN2048 `[\s\S]{0,2048}`	Optional
`merchant.foreignRetailIndicator`	The merchant's Foreign Retail Indicator.	AN25	Optional
`merchant.legalName`	The merchant's legal name.	AN100	Optional

Cart and marketplace

Cart items

The cart data structure holds product information about the shopping cart such as the product's ID, name, quantity, and price. Count up the cart items by changing the index-number [n], starting with 0, and a maximum of 1000, for example, cart.items[0].name=First Cart Item.

Parameter	Description	Format	Condition
`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 the purchased item type in the shopping cart. Values can be: `PHYSICAL`, `DIGITAL`, `MIXED`, `ANONYMOUS_DONATION`, `AUTHORITIES_PAYMENT`.	AN255 `[\s\S]{1,255}`	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].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].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].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].taxCategory`	The mandatory L3 card data tax category. Values: `AA`, `S`, `E`, or `Z`.	AN2	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].sku`	The SKU of the cart item.	AN255 `[\s\S]{1,255}`	Optional
`cart.items[n].commodityCode`	Product commodity code for L3 card data. See list at UNSPSC.	N8	Optional
`cart.items[n].commodityDescription`	Product commodity description for L3 card data. See list at UNSPSC.	AN50	Optional
`cart.items[n].originalPrice`	The price of the item in the shopping cart, excluding tax and discount. The item's price is independent of the quantity.	AN255 `[\s\S]{1,255}`	Optional
`cart.items[n].giftMessage`	The gift message for the specific cart item.	AN255 `[\s\S]{1,255}`	Optional
`cart.items[n].shippingMethod`	The shipping method for the cart item.	AN255 `[\s\S]{1,255}`	Optional
`cart.items[n].shippingInstructions`	The shipping instructions for the cart item.	AN255 `[\s\S]{1,255}`	Optional
`cart.items[n].shippingTrackingNumber`	The shipping tracking number for the cart item.	AN255 `[\s\S]{1,255}`	Optional
`cart.items[n].quantityUnit`	The cart item's unit of quantity.	`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 relates to the discount percentage.	N10.N2 `[0-9]{1,10}\\.[0-9]{2}`	Optional
`cart.items[n].productCode`	The cart item's product code given by the merchant for identification.	AN30 `[\s\S]{1,30}`	Optional
`cart.items[n].partNumber`	The cart item's manufacturer-provided part number.	AN30 `[\s\S]{1,30}`	Optional
`cart.items[n].itemNumber`	The cart item's line number of this item on the invoice.	N3 `{1,999}`	Optional
`cart.items[n].vatReferenceNumber`	The cart item's reference number used to identify the VAT invoice or tax receipt.	AN30 `[\s\S]{1,30}`	Optional
`cart.items[n].sellerId`	The unique identifier of the marketplace seller to which this cart item belongs.	AN255 `[\s\S]{1,255}`	Optional
`cart.items[n].recipient.salutation`	The cart item's recipient title.	AN5 `[\s\S]{1,5}`	Optional
`cart.items[n].recipient.firstName`	The cart item's recipient first name.	AN48 `[\s\S]{1,48}`	Optional
`cart.items[n].recipient.middleName`	The cart item's recipient middle name.	AN50 `[\s\S]{1,50}`	Optional
`cart.items[n].recipient.lastName`	The cart item's recipient last name.	AN48 `[\s\S]{1,48}`	Optional
`cart.items[n].recipient.apartment`	The cart item's recipient apartment number.	AN100 `[\s\S]{1,100}`	Optional
`cart.items[n].recipient.street`	The cart item's recipient address line 1.	AN100 `[\s\S]{1,100}`	Optional
`cart.items[n].recipient.address`	The cart item's recipient address line 2.	AN100 `[\s\S]{1,100}`	Optional
`cart.items[n].recipient.city`	The cart item's recipient city.	AN80 `[\s\S]{1,80}`	Optional
`cart.items[n].recipient.state`	The cart item's recipient state.	AN50 `[\s\S]{1,50}`	Optional
`cart.items[n].recipient.postcode`	The cart item's recipient postal code.	AN16 `[\s\S]{1,16}`	Optional
`cart.items[n].recipient.country`	The cart item's recipient country code.	A2 `[A-Za-z]{2}` or N3 `[0-9]{3}`	Optional
`cart.items[n].recipient.phone`	The cart item's recipient phone number.	N25 `[0-9]{1,25}`	Optional
`cart.items[n].recipient.email`	The cart item's recipient email address.	AN128 `[\s\S]{1,128}`	Optional
`cart.items[n].deliveryDate`	The cart item's 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

Cart payments

The cart payments data structure holds information about already made payments associated with the cart. Count up the cart payments by changing the index number [n], starting with 0, for example, cart.payments[0].name=First Cart Item.

Parameter	Description	Format	Condition
`cart.payments[n].name`	The name of the payment method. Example: `cart.payments[0].name=promotion giftcard 50`	AN255 `[\s\S]{1,255}`	Optional
`cart.payments[n].type`	The payment type used. One of the options: `GIFTCARD`, `PROMOTION`. Example: `GIFTCARD`	AN255 `[\s\S]{1,255}`	Optional
`cart.payments[n].amount`	The amount of the associated and already used payment method. Example: `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: `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: `captured`	AN255 `[\s\S]{1,255}`	Optional
`cart.payments[n].brand`	The brand of the already used payment method, for example, `SVS`. Example: `SVS`	AN255 `[\s\S]{1,255}`	Optional
`cart.payments[n].primary`	Identifies this payment method as the primary payment method used for that cart. One of the options: `true`, `false`. Example: `false`	true\|false	Optional

Marketplace

The marketplace data structure holds information about the sellers such as ID, amount, and items. Send the items associated with each seller in cart items fields, identifying each item by the value in the cart.items[n].sellerId field. Count up the sellers by changing the index number [n], starting with 0, for example marketPlace.sellers[0].id=2391.

Parameter	Description	Format	Condition
`marketPlace.sellers[n].id`	The unique identifier of the seller.	AN255 `[\s\S]{1,255}`	Optional
`marketPlace.sellers[n].amount`	The total amount of the items under the seller.	N13 `[0-9]{1,10}\\.[0-9]{2}`	Optional

Airline

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

Parameter	Description	Format	Condition
`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 customer made the booking.	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 customer booked their ticket via a third party.	AN255 `[\s\S]{1,255}`	Conditional
`airline.bookingtype`	The booking type.	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].residenceCountry`	The residence country code of the passenger (ISO 3166-1).	A2 ISO country code `[A-Za-z]{2}`	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 customer can stop over.	AN255 `[\s\S]{1,255}`	Conditional
`airline.passengers[n].legs[n].restrictions`	Indicates if there are 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
`airline.passengers[n].legs[n].timeToDeparture`	The airline time to departure, in days, for the leg.	AN10 `[\s\S]{1,10}`	Conditional

Tokenisation and registration

You can store a customer's data in two ways on the system. You can either directly POST to the registration endpoint or add the following parameter to a payment:

Parameter	Description	Format	Required
`createRegistration`	If true, Peach Payments stores the payment details with the request. As part of the response, you receive the parameter `registration.id`, which you can use to reference the registration for later payments.	true\|false	Optional
`overrideHolder`	If true, you can send the `card.holder` or `bankAccount.holder` to override the empty holder from the registration/tokenisation transaction. It applies only to that particular payment and does not change the holder value of the registration transaction. For one-click payments, the edit box appears as a replacement over the empty label, allowing the user to input the new value for the holder. This parameter is available during the prepare (and update) checkout step of COPYandPAY, as well as when sending the payment over registration one-click payment Server-to-Server.	true\|false	Optional

3-D Secure

The 3-D Secure data structure holds authentication data generated by the 3-D Secure MPI when you're using an external MPI, or extra information about the authentication. If 3-D data is present, which indicates the usage of an external MPI (xid, eci, verificationId), the payment gateway passes these values through to the acquiring system. For more detailed information about the required fields for 3-D Secure version 2.0 and above, visit the 3-D Secure 2.0 guide.

Parameter	Description	Format	Required
`threeDSecure.eci`	The ECI for the 3-D Secure request. Required when using a third-party MPI. Example: `threeDSecure.eci=01`	N2 `(0[1-8]{1})`	Conditional
`threeDSecure.verificationId`	The 3-D Secure CAVV or AAV. Required when using a third-party MPI. Must be Base64 encoded.	AN28 `([\s\S]{28})`	Conditional
`threeDSecure.xid`	The 3-D Secure XID if available. Must be Base64 encoded.	AN64 `([\s\S]{64})`	Conditional
`threeDSecure.enrollmentStatus`	The enrolment status for the 3-D Secure request. Required when using a third-party MPI.	AN1 `([YUN])`	Conditional
`threeDSecure.authenticationStatus`	The authentication status for the 3-D Secure request. Required when using a third-party MPI.	AN1 `([YAUN])`	Conditional
`threeDSecure.deviceInfo`	Encrypted device information. Required when initialising the 3-D Secure version 2's app-based flow. Retrieve the value from the mobile SDK `authRequestParams`.	As returned by `authRequestParams`	Conditional
`threeDSecure.amount`	Amount for which the shopper is authenticating.	N9.N2 `([0-9]{1,9}\\.[0-9]{2})`	Optional
`threeDSecure.currency`	Currency for which the shopper is authenticating.	A3 (ISO 4217 currency code)	Optional
`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.v2.visa.requestorId`	Requestor ID for 3-D Secure v2, assigned by Visa.	AN100 `([\s\S]{100})`	Optional
`threeDSecure.v2.visa.requestorName`	Requestor Name for 3-D Secure v2, assigned by Visa.	AN100 `([\s\S]{100})`	Optional
`threeDSecure.v2.mastercard.requestorId`	Requestor ID for 3-D Secure v2, assigned by Mastercard.	AN100 `([\s\S]{100})`	Optional
`threeDSecure.v2.mastercard.requestorName`	Requestor Name for 3-D Secure v2, assigned by Mastercard.	AN100 `([\s\S]{100})`	Optional
`threeDSecure.v2.amex.requestorId`	Requestor ID for 3-D Secure v2, assigned by American Express.	AN100 `([\s\S]{100})`	Optional
`threeDSecure.v2.amex.requestorName`	Requestor Name for 3-D Secure v2, assigned by American Express.	AN100 `([\s\S]{100})`	Optional
`threeDSecure.v2.diners.requestorId`	Requestor ID for 3-D Secure v2, assigned by Diners/Discover.	AN100 `([\s\S]{100})`	Optional
`threeDSecure.v2.diners.requestorName`	Requestor Name for 3-D Secure v2, assigned by Diners/Discover.	AN100 `([\s\S]{100})`	Optional
`threeDSecure.v2.jcb.requestorId`	Requestor ID for 3-D Secure v2, assigned by JCB.	AN100 `([\s\S]{100})`	Optional
`threeDSecure.v2.jcb.requestorName`	Requestor Name for 3-D Secure v2, assigned by JCB.	AN100 `([\s\S]{100})`	Optional
`threeDSecure.v2.cartebancaire.requestorId`	Requestor ID for 3-D Secure v2, assigned by Carte Bancaire.	AN100 `([\s\S]{100})`	Optional
`threeDSecure.v2.cartebancaire.requestorName`	Requestor Name for 3-D Secure v2, 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 3-D Secure v2, using an external MPI.	AN100 `([\s\S]{36})`	Optional
`threeDSecure.acsTransactionId`	Universally unique transaction identifier assigned by the ACS to identify a single transaction. Used when the transaction was already authenticated via 3-D Secure v2, using an external MPI.	AN100 `([\s\S]{36})`	Optional
`threeDSecure.version`	Version of the 3-D Secure used when the transaction was already authenticated using an external MPI. For example: 2.1.0 or 2.2.0.	`(1\|2)\\.[0-9]\\.[0-9]`	Optional
`threeDSecure.challengeIndicator`	Indicates whether to request a challenge for this transaction. Sometimes sent when you use 3-D Secure version 2.2 or higher.	`0[1-9]`	Optional
`threeDSecure.challengeMandatedIndicator`	Indicates whether to request a challenge for the transaction for the customer to authorise due to local or regional mandates or other variable. Sometimes used when an external MPI authenticated the transaction.	AN1 (Y\|N)	Optional
`threeDSecure.authType`	The authentication type requested by the ACS. Sometimes used when an external MPI authenticated the transaction.	AN2 `(0[1-4])`	Optional
`threeDSecure.exemptionFlag`	Flags the transaction as an exemption during authorisation. Sometimes sent when you use 3-D 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. Sometimes used when an external MPI authenticated the transaction.	N2	Optional
`threeDSecure.channel`	The authentication channel indicator. Provide this only to note a 3RI request (merchant-initiated authentication), a feature available in 3DS 2.2 for Mastercard only. Sometimes used when an external MPI authenticated the transaction.	N2 `(0?[1-9]\|[1-9][0-9])`	Optional

Custom parameters

Use custom parameters to send custom data. Peach Payments echoes back the data sent in these fields in the response.

Parameter	Description	Format	Condition
`customParameters[name]`	A name-value pair used for sending custom information. Prepend `customParameters` that you send from the client-side (for example, for COPYandPAY) with `SHOPPER_*`, for example `customParameters[SHOPPER_customerId]`.	name: AN64 `([a-zA-Z0-9\\._]{3,64})` value: AN2048 `([\s\S]{0,2048})`	Conditional
`threeDSecure.schemeData[CB-ITEMSNB]`	This field represents the number of items or services purchased. You must include this field to process 3DS transactions for the Carte Bancaire scheme and you can use it for 3-D Secure v2.	N2	Conditional but recommended
`threeDSecure.schemeData[CB-SCORE_MERCHANT]`	The merchant score, calculated by the 3DS requestor and provided to the card scheme scoring service only. You must include this field to process 3DS transactions for the Carte Bancaire scheme and you can use it for 3-D Secure v2.	`[a-zA-Z0-9\\s+-:]{1-20}`	Conditional but recommended
`threeDSecure.schemeData[CB-USECASE]`	The payment authentication use case. It indicates the payment type for which you requested authentication. You must include this field to process 3DS transactions for the Carte Bancaire scheme and you can use it for 3-D Secure v2.	N2	Conditional (required if message category = PA, or message category = NPA and 3DS requestor authentication indicator = 02 or 03)

Asynchronous payments

Asynchronous payment methods like 3-D Secure, online transfer, or virtual wallets have extra steps in their workflow. The response to your initial payment request is pending and contains a redirect URL to the receiver system that you should forward the shopper to.

Parameter	Description	Format	Condition
`shopperResultUrl`	This URL received the result of an asynchronous payment. Use it to redirect the shopper to the merchant's website or application. You must send it in URL-encoded format and it must be an absolute URL.	AN2048 `[\s\S]{6,2048}`	Conditional
`notificationUrl`	Deprecated. Follow webhooks configuration and do not use the request parameter `notificationUrl`. Due to the variety of payment workflows and checkout options, the `notificationUrl` parameter is not fully compatible with all activities. Use webhook notifications instead. This URL receives the asynchronous notification where applicable and receives the transaction status update on asynchronous payments. It must be in URL-encoded format.	AN2048 `[\s\S]{6,2048}`	Optional

Response parameters

Parameter	Description	Format	Condition
`redirect.url`	Redirect the shopper to this URL 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` as described 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 receive notifications on the registered URL. These notifications are standard responses (wrapped in the payload) of different types.

Parameter	Description	Format	Condition
`type`	Notification type: - `PAYMENT`: Sent when the system creates or updates a payment. - `REGISTRATION`: Sent when the system creates a new registration or deletes an existing registration.	PAYMENT\|REGISTRATION	Required
`payload`	Content of the notification. If the notification type is payment or registration, `payload` is the same as the payment response you received.	JSON	Required
`action`	Indicator of status change: - `CREATED`: When the system creates a registration. - `UPDATED`: When the system updates a registration. - `DELETED`: When the system deletes a registration.	CREATED\|UPDATED\|DELETED	Conditional

In addition to standard response parameters, these notification-specific fields are available:

Parameter	Description	Format	Condition
`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

Reporting

Use the following parameters when calling the reporting endpoints.

Parameter	Description	Format	Condition
`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
`sortValue`	The value which sorts the Detail Level settlement report.	SettlementTxDate	Optional
`sortOrder`	The order which sorts the Detail Level settlement report output.	ASC\|DESC\|asc\|desc	Optional

Giftcard

A gift card allows you to send extra information for payments and risk checks that involve a gift card.

Parameter	Description	Format	Condition
`giftCard.number`	The gift card number.	AN255 `[\s\S]{2,255}`	Optional
`giftCard.pin`	The gift card PIN.	AN255 `[\s\S]{2,255}`	Optional
`giftCard.holder`	The holder of the gift card.	AN255 `[\s\S]{2,255}`	Optional
`giftCard.message`	Message written on the gift card.	AN160 `[\s\S]{2,160}`	Optional
`giftCard.type`	Gift card type: 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 extra parameters available for risk checks, for example, using the ReD Shield.

Parameter	Description	Format	Condition
`risk.channelId`	ID of the channel in the risk system. This field is generally set up as a configuration. For ReD Shield, this executes a different set of rules. In that case, the maximum length is AN12.	AN255 `[\s\S]{1,255}`	Optional
`risk.serviceId`	ID of the service in the risk system. This field is generally set up as a configuration. For ReD Shield, this defines which fraud screening service to use. In that case, the maximum length is AN1.	AN255 `[\s\S]{1,255}`	Optional
`risk.amount`	Amount for the risk request. The dot is the decimal separator. This parameter is for both ReD Shield and 3-D Secure. When performing the 3-D Secure, if this parameter is present, it is the amount for the 3-D 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), for example, `2015-12-17 22:00:04`. By default, the payment system sets a timestamp automatically. Use this field when the (payment) transaction executes at a different time than the risk request.	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 you're checking. 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.	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

Scheduling

Use the following parameters to schedule subscription payment jobs.

🚧
Specifying both a dayOfWeek and a dayOfMonth value is not supported. Use the ? character in one of these fields.

Parameter	Description	Format	Condition
`job.name`	The name of the job that you're scheduling. Used for identification purposes only.	AN64 `[\s\S]{1,64}`	Optional
`job.year`	The specific year to execute.	AN64 `empty`, `1970-2099`, `, - * /` Default: `*`	Optional
`job.month`	The specific month to execute (Jan - Dec).	AN64 `1-12`, `, - * /` Default: `1`	Optional
`job.dayOfMonth`	The specific day in the month to execute.	AN64 `1-31`, `, - * ? / L W` Default: `1`	Optional
`job.dayOfWeek`	The specific day in the week to execute.	AN64 `1-7`, `SUN-SAT`, `, - * ? / L #` Default: `1`	Optional
`job.hour`	The specific hour to execute.	AN64 `0-23`, `, - * /` Default: `0`	Optional
`job.minute`	The specific minute to execute.	AN64 `0-59`, `, - * /` Default: `0`	Optional
`job.second`	The specific second to execute.	AN64 `0-59`, `, - * /` Default: `0`	Optional
`job.startDate`	The date and time to execute the job.	AN19 `yyyy-MM-dd HH:mm:ss`	Optional
`job.endDate`	The date and time to end the job.	AN19 `yyyy-MM-dd HH:mm:ss`	Optional
`job.noticeUnit`	The unit of the cancellation notice period.	YEAR\|MONTH\|WEEK\|DAY\|HOUR\|MINUTE\|SECOND	Optional
`job.noticeNumber`	The time in advance required by the cancellation notice to avoid a prolongation of the job period.	N16	Optional
`job.noticeCallable`	The reference point for the cancellation notice.	ANYTIME\|DURATION_END	Optional
`job.durationUnit`	The unit of the job period duration.	YEAR\|MONTH\|WEEK\|DAY\|HOUR\|MINUTE\|SECOND	Optional
`job.durationNumber`	The duration of the job period.	N16	Optional
`job.expression`	The cron expression representing how often the job executes. A cron expression is a string comprised of 7 fields, while the `job.year` is optional. It overwrites `second`, `minute`, `hour`, `dayOfMonth`, `month`, `dayOfWeek`, and `year` in this order.	AN256	Optional

Payment response parameters

❗
The API response is in a JSON format. This approach allows ensures flexibility in extending the API schema by adding new fields at any time to add new product functionality. Ensure your integration is parsing the JSON response and is able to handle newly added response fields without any service interruption.

Parameter	Description	Format	Condition
`id (/checkouts)`	The identifier of the checkout request. You can use this 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. You can use this 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.	AN32 `[a-zA-Z0-9]{32}`	Required
`id (/registrations)`	The identifier of the registration request. You can use this 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`).	AN32 `[a-zA-Z0-9]{32}`	Required
`result.code`	The unique code that indicates the result status of the request. See the response codes for more detailed information.	AN11 `[0-9\\.]{2,11}`	Required
`merchant.bankAccount.holder`	Holder of the merchant's bank account.	AN128 `{4,128}`	Required
`buildNumber`	Useful for support purposes.	AN255 `[\s\S]{0,255}`	Required
`timestamp`	The timestamp when the system generated the response.	Date yyyy-MM-dd hh:mm:ssZ	Required
`ndc`	An internal unique identifier for the request.	AN69 `[a-zA-Z0-9\-]{1,69}`	Required
`referencedId`	In case of referenced payment (for example, capture or refund), use this field to see which payment the system referenced. This field is only for webhook notifications.	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 transaction approved by the acquirer, alternative payment method, or other payment platform.	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.avsResponse`	Contains the AVS response returned by the acquirer. Possible results: `A` = Address matches, zip code does not match; `Z` = Address does not match, zip code matches; `N` = Neither matches; `U` = Error or unavailable; `F` = Both match.	A1 `[A-Z]{1}`	Conditional
`result.cvvResponse`	Contains the CVV response returned by the acquirer. Possible values include: `M` = Match, `N` = Does not match, `P` = Not processed, `S` = Data missing but required, `U` = Unsupported or error.	A1 `[A-Z]{1}`	Conditional
`resultDetails.AcquirerResponse`	Represents the acquirer's original response code retrieved directly.	AN2048 `[\s\S]{0,2048}`	Conditional
`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. A value between -99999 to +99999.	AN6 `[-+]?[0-9]{5}`	Conditional
`Other`	The response can also contain each of the data structures listed above, such as `customer` and `billingAddress`.	Not applicable	Conditional
`result.description`	A textual description explaining the `result.code`'s meaning.	AN255 `[\s\S]{0,255}`	Optional
`resultDetails`	A container for name-value pairs enriching the response with bank-specific details. For example: `resultDetails.AuthCode=123456`.	Name: AN64 `[a-zA-Z0-9\\._]{3,64}` Value: AN2048 `[\s\S]{0,2048}`	Optional
`resultDetails.MerchantAdviceCode`	Represents information about the reason for a decline and the next actions for a transaction. Check specific integration documentation to confirm support for this field.	N2 `[\d]{2}`	Optional
`card.bin`	The first six digits of the `card.number`.	N6 `[\d]{6}`	Optional
`card.holder`	Holder of the credit card account.	A128 `{3,128}`	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
`card.issuer.bank`	The issuer name.	AN2048 `[\s\S]{0,2048}`	Optional
`card.issuer.phone`	The phone number of the issuer.	AN2048 `[\s\S]{0,2048}`	Optional
`card.issuer.website`	The website of the issuer.	AN2048 `[\s\S]{0,2048}`	Optional
`card.type`	The card type, for example, CREDIT.	AN2048 `[\s\S]{0,2048}`	Optional
`card.level`	The level of the card, for example, DEFERRED DEBIT.	N4 `[\d]{4}`	Optional
`card.regulatedFlag`	Indicates whether it's a regulated or unregulated card, for example, `true` or `false`.	AN2048 `[\s\S]{0,2048}`	Optional
`brandResult`	Detected brand.	A16	Optional

Reconciliation response parameters

Reconciliation reporting data is available via a CSV file from FTP. The structure of the reconciliation reporting CSV file is as follows: ReconciliationType, PaymentType, Cashflow, ClearingInstituteMerchantId, MerchantAccountId, MerchantAccountName, PspId, DivisionId, MerchantId, SettlementTxId, UniqueID, ShortId, ConnectorTxId1, ConnectorTxId2, ConnectorTxId3, Amount, Currency, Brand, TxRequestTime, SettlementAmount, SettlementCurrency, SettlementFee, SettlementFxRate, SettlementDate, SettlementStatus, Descriptor, AccountNumberLast4, BankCode, AccountHolder, ReasonCode, ReasonDesc, SettlementFileFormat, ClearingInsitituteName, MatchingStatus, MatchedTransactions, and ChargebackId.

CSV parameter	API parameter	Description	Format	Condition
`Cashflow`	`settlement.cashflow`	Transaction balance direction.	`POS`, `NEG`	Required
`SettlementAmount`	`settlement.amount`	Settled amount.	N13 `[0-9]{1,10}\\.[0-9]{2}`	Required
`SettlementCurrency`	`settlement.currency`	Settlement currency (ISO 4217).	A3	Required
`SettlementFxRate`	`settlement.fxRate`	Settlement foreign exchange rate.	N13 `[0-9]{1,10}\\.[0-9]{2}`	Required
`SettlementDate`	`settlement.date`	Date on which the clearing institute executed settlement in its time zone.		Required
`SettlementStatus`	`settlement.status`	Settlement status.	`SUCCESS`, `FAILED`	Required
`SettlementFileFormat`	`settlement.format`	File format of settlement file.	AN32	Required
`ClearingInsitituteName`	`clearingInstitute.name`	Name of clearing institute.	AN64	Required
`ClearingInstituteMerchantId`	`clearingInstitute.merchantId`	Merchant ID at settlement provider.	AN64 `[\s\S]{5..64}`	Required
`MerchantAccountId`	`merchantAccount.id`	Account ID of merchant.	AN32 `[a-zA-Z0-9]{32}`	Required
`ReconciliationType`	`recordType`	Record type.	`SETTLED`, `CHARGEBACK`, and so on	Required
`PaymentType`	`transactionType`	Transaction type.	`DEBIT`, `CREDIT`, and so on	Required
`PspId`	`pspEntityId`	ID of PSP.	AN32 `[a-zA-Z0-9]{32}`	Required
`MerchantId`	`merchantEntityId`	ID of merchant.	AN32 `[a-zA-Z0-9]{32}`	Required
`TransactionId`	`merchantTransactionId`	Unique reference number provided by merchant or generated by the gateway.	AN255 `[\s\S]{8,255}`	Required
`Amount`	`amount`	Transaction amount.	N13 `[0-9]{1,10}\\.[0-9]{2}`	Required
`Currency`	`currency`	Transaction currency (ISO 4217).	A3	Required
`MatchingStatus`	`matchedTransactions.status`	The matching status of the corresponding transaction in the gateway.	`MATCHED`, and so on	Conditional
`MatchedTransactions`	`matchedTransactions.payment[n].id`	Unique IDs of the matched transactions.	AN32 `[a-zA-Z0-9]{32}`	Conditional
`ChargebackId`	`chargebackTransaction.id`	The unique ID of the chargeback transaction generated by the gateway after matching a chargeback record.	AN32 `[a-zA-Z0-9]{32}`	Conditional
`ReasonCode`	`result.code`	Failure status code (available only for chargebacks).	AN11 `[0-9\\.]{2,11}`	Optional
`ReasonDesc`	`result.description`	Failure status description (available only for chargebacks).	AN128	Optional
`SettlementTxId`	`settlement.id`	Transaction ID at settlement provider.	AN64 `[\s\S]{0,64}`	Optional
`SettlementFee`	`settlement.fee`	Settlement fee.	N13 `[0-9]{1,10}\\.[0-9]{2}`	Optional
`ConnectorTxId1`	`clearingInstitute.txId1`	Extra field for a transaction-related reference (provided by the clearing institute).	AN64	Optional
`ConnectorTxId2`	`clearingInstitute.txId2`	Extra field for a transaction-related reference (provided by the clearing institute).	AN64	Optional
`ConnectorTxId3`	`clearingInstitute.txId3`	Extra field for a transaction-related reference (provided by the clearing institute).	AN64	Optional
`AccountNumberLast4`	`card.last4Digits`	Last four digits of the credit or debit card.	AN4	Optional
`AccountHolder`	`card.holder`	Account holder of credit or debit card account.	AN128	Optional
`AccountNumberLast4`	`bankAccount.last4Digits`	Last four digits of the bank account.	AN4	Optional
`BankCode`	`bankAccount.bankCode`	Bank code or BIC in case the transaction is bank-related.	AN12	Optional
`AccountHolder`	`bankAccount.holder`	Account holder of bank account.	AN128	Optional
`MerchantAccountName`	`merchantAccount.name`	Name of merchant.	AN32 `[a-zA-Z0-9]{32}`	Optional
`UniqueID`	`payment.id`	Unique ID of payment transaction in gateway.	AN32 `[a-zA-Z0-9]{32}`	Optional
`DivisionId`	`divisionEntityId`	ID of division.	AN32 `[a-zA-Z0-9]{32}`	Optional
`ShortId`	`-`	Short ID of payment transaction in gateway.	AN14	Optional
`InvoiceId`	`merchantInvoiceId`	Invoice ID provided by merchant.	AN255 `[\s\S]{8,255}`	Optional
`Brand`	`paymentBrand`	Brand of the payment method.	A16	Optional
`TxRequestTime`	`presentmentDate`	Time of ordering the transaction by the merchant in clearing institute's time zone.		Optional
`Descriptor`	`descriptor`	Transaction reference which appears on the end customer's statement.	AN128	Optional

Card on file

The parameters needed for sending card on file transactions are as follows.

Parameter	Description	Format	Condition
`standingInstruction.type`	The category of the transaction. RECURRING: Recurring transactions occur on a regular fixed interval for a pre-agreed or advised amount. These transactions continue until cancelled by the cardholder. INSTALLMENT: Installment payments occur on a fixed interval for a single purchase. They have a fixed duration and end after the agreed instalment period. UNSCHEDULED: An unscheduled credential-on-file transaction happens at non-pre-agreed intervals, such as pay-as-you-go thresholds.	`UNSCHEDULED`, `INSTALLMENT`, `RECURRING`	Conditional
`standingInstruction.recurringType`	Indicates the recurring MIT agreement type. STANDING_ORDER: Used when a consumer agrees to store credentials for transactions with variable amounts and fixed frequency (for example, utility payments). SUBSCRIPTION: Used when a consumer agrees to store credentials for transactions with fixed amounts and fixed frequency (for example, monthly subscriptions). Note: Required for all Mastercard CIT or MIT transactions and for Visa recurring transactions for cards issued in India.	`STANDING_ORDER`, `SUBSCRIPTION`	Conditional
`standingInstruction.mode`	Indicates the mode of subsequent payment transactions. INITIAL: The first of a series of payments, requiring extra data like CVV or 3-D Secure parameters. REPEATED: Subsequent payments without shopper authentication data like CVV or 3-D Secure parameters.	`INITIAL`, `REPEATED`	Conditional
`standingInstruction.source`	Indicates the subsequent payment transaction type. CIT: Cardholder-initiated transactions. MIT: Merchant-initiated transactions.	`CIT`, `MIT`	Conditional
`standingInstruction.initialTransactionId`	Represents the reference ID generated by the scheme (or processor-specific ID). Required for MIT transactions when the card isn't tokenised by the platform. Specific OPP responses provide the ID.	AN or N (varies by acquirer)	Conditional
`standingInstruction.industryPractice`	MIT types for business practices as a follow-up to original cardholder-merchant interactions: INCREMENTAL_AUTH: Adds to the total authorised amount. RESUBMISSION: Re-attempts authorisation after insufficient funds. REAUTHORIZATION: Submits authorisation requests after the cardholder leaves the interaction point. DELAYED_CHARGES and NO_SHOW: Used in rental and hospitality sectors, requiring initial authorisation data.	`INCREMENTAL_AUTH`, `RESUBMISSION`, `REAUTHORIZATION`, `DELAYED_CHARGES`, `NO_SHOW`	Conditional
`standingInstruction.expiry`	Date after which you cannot perform further authorisations. Used for EMV 3-D Secure authentication requests. - Mastercard: Default value `9999-12-31` if not provided. - Other brands: Authentication request sent with "payment" indicator (not "recurring") if not provided. Required for recurring or instalment transactions requiring 3-D Secure authentication.	`yyyy-mm-dd`	Conditional
`standingInstruction.frequency`	Minimum number of days between authorisations. - Mastercard: Default value `0001` if not provided by the customer. - Other brands: Authentication request sent with "payment" indicator (not "recurring") if not provided. Mandatory for recurring or instalment transactions requiring 3-D Secure authentication.	N4	Conditional
`standingInstruction.numberOfInstallments`	Maximum number of authorisations for instalment payments. Required if the merchant and cardholder agree to instalment payments, and you have configured EMV 3-D Secure authentication (`standingInstruction.type=INSTALLMENT`). Omitted if not an instalment payment. Mandatory for instalment transactions requiring 3-D Secure authentication.	N3	Conditional

Chargeback

Use the following parameters for chargeback back-office operations.

Parameter	Description	Format	Condition
`chargebackResultCode`	The chargeback reason code for the chargeback as received from the acquirer. See the chargeback response codes for more detailed information.	`000\.100\.2[0-9]{2}`	Optional

Query

Use the following parameters for OPP query requests.

Parameter	Description	Format	Condition
`merchantTransactionId`	The merchant reference sent in the request. Generally used to identify an order in the order management system and used as end-to-end identifier for reconciliation. Do not use when querying a duration using `date.from`/`date.to` parameters.	AN255	Optional
`limit`	The maximum number of transactions that the system returns in the query response. Defaults to 100 if not explicitly set. Valid range: 100–500.	Numeric values between 100 and 500	Optional
`date.from`	The start timestamp from which the system should query transactions should. Use together with the end of interval `date.to`.	yyyy-MM-dd HH:mm:ss	Optional
`date.to`	The end timestamp before which the system should query transactions should. Use together with the start of interval `date.from`.	yyyy-MM-dd HH:mm:ss	Optional
`paymentTypes`	Indicates payment types by which the system should filter transactions. Possible values include: `CB`, `CD`, `CR`, `DB`, `CP`, `IV`, `PA`, `RB`, `RC`, `RF`, `RL`, `RV`, `AD`, `IN`, `FI`, `CL`, `CF`, `DR`, `RG`, `RR`, `TE`, `CT`, `DS`, `RS`, `SD`, `AC`, `MD`, `EA`, `RI`, `3D`, `SA`, `EN`, `ID`, `IC`, `DP`, `CG`, `TG`, `SF`, `IS`, `VD`, `DV`, `AF`, `GK`, `RD`, `TM`, `FT`, `KT`, `AR`, `AL`, `PL`, `FN`, `FZ`, `RE`, `RX`, `FO`, `CS`, `EX`, `SE`, `AU`, `TK`, `TF`, `ER`. Example: `paymentTypes=PA,DB`	Comma-separated list of payment types	Optional
`paymentMethods`	Indicates payment methods by which the system should filter transactions. Possible values include: `DD`, `CT`, `CC`, `WA`, `VA`, `UA`, `OT`, `DC`, `ET`, `NT`, `IV`, `PP`, `OD`, `RM`. Example: `paymentMethods=CC,RM`	Comma-separated list of payment methods	Optional
`includeLinkedTransactions`	Indicates whether the system should return all transactions linked with the one provided in the query request.	true \| false	Optional
`shortId`	Indicates the `shortId` by which the system should filter the transactions.	AN14	Optional