API Reference

You can perform different types of initial payments using our server-to-server REST API.

• Preauthorization
• Capture
• Payment
• Reversal
• Refund
• Inquiry

Common Parameters

Authentication Parameters

The entityId and entityType, Each merchant and institution will have its own entityId, which are included in the request message body (entityId and merchant ID can be the same).

	Required	Format	Description
entityId	Required	AN8[A-Z0-9]8	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.
entityType	Required	AN32	Entity type of the channel, possible value:MERCHANT POS PARTICIPATOR PARTICIPATOR

Payment Request Parameters

	Required	Format	Description
card.holder	Optional	A128128	Holder of the credit card account
card.number	Optional	N19[0-9]19	The PAN or account number of the card. If the request contains the card.token field, the card.number and other related information are not required.
card.expiryMonth	Conditional	N2(0[1-9]|1[0-2])	The expiry month of the card.
card.expiryYear	Conditional	N4(19|20)([0-9]2)	The expiry year of the card.
card.cvv	Conditional	N4[0-9]4	The card security code or CVV
card.token	Conditional	AN64	Globally unique identifier for the Token (TUR)
amount	Conditional	N10.N2[0-9]10(.[0-9]2)	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. The amount field can be skipped for paymentType=CV
currency	Conditional	A3[A-Z]3	The currency code of the payment request's amount (ISO 4217).
paymentBrand	Conditional	AN32[a-zA-Z0-9_]32	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.
paymentType	Required	A2	The payment type for the request. You can send payment requests with one of the following types: PA Preauthorization: A stand-alone authorisation that will also trigger optional risk management and validation. A Capture (CP) with reference to the Preauthorisation (PA) will confirm the payment. DB Debit: Debits the account of the end customer and credits the merchant account. CD Credit: Credits the account of the end customer and debits the merchant account. CP Capture: Captures a preauthorized (PA) amount. CV Verification: Card verification RV Reversal: Reverses an already processed Preauthorization (PA), Debit (DB) or Credit (CD) transaction. As a consequence, the end customer will never see any booking on his statement. A Reversal is only possible until a connector specific cut-off time. Some connectors don't support Reversals. RF E-commerce Refund: Credits the account of the end customer with a reference to a prior Debit (DB) or Credit (CD) transaction. The end customer will always see two bookings on his statement. PR POS Refund: Credits the cardholder account with a reference to a prior POS Purchase transaction.
taxAmount	Conditional	N10.N2[0-9]10(.[0-9]2)	Indicates the tax amount of the payment request. The dot is used as decimal separator.
descriptor	Optional	AN127[\s\S]127	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.
transactionSource	Conditional	AN32[a-zA-Z0-9_]32	Transaction Source is optional in payment request and it is mandatory in Reversal Transactions. The possible value maybe: CARDHOLDER, TOKEN,...etc.
merchantInvoiceId	Optional	AN255[\s\S]255	Merchant-provided invoice number, should be unique for your transactions. This identifier is not sent onwards.
merchantMemo	Optional	AN255[\s\S]255	Merchant-provided additional information. The information provided is not transaction processing relevant. It will appear in reporting only.
transactionCategory	Optional	AN32[a-zA-Z0-9]32	The category of the transaction, possible values are: EC - eCommerce MO - Mail order TO - Telephone order RC - Recurring IN - Installment PO - POS PM - mPOS
merchant.id	Mandatory	N15[0-9]15	Acquirer-assigned Merchant identifier.
pos.terminalId	Optional	AN8[a-zA-Z0-9_]8	Terminal Id assigned by the acquirer.
merchantTransactionId	Required	AN32[a-zA-Z0-9]32	Merchant-provided reference number, should be unique for your transactions. Some receivers require this ID. This identifier is often used for reconciliation. Each transaction requires a unique merchant transaction ID. The reversal and refund have their own merchant transaction ID, which is different from the original transaction.
validityPeriod	Optional	N8	Transaction will be closed automatically after the period. (Unit: millisecond)
checkoutType	Optional	AN10[a-zA-Z0-9_]10	Transaction type of checkout page transaction. possible values are: AUTHORIZE Preauthorization: A stand-alone authorisation that will also trigger optional risk management and validation. A Capture (CP) with reference to the Preauthorisation (PA) will confirm the payment. PURCHASE Debits the account of the end customer and credits the merchant account.
threeDSecure. indicator	Conditional	force/true	- The indicator will be ignored if the merchant 3DS authentication is not optional. force: The transaction need go through Risk System (such as DM), although it go through Risk System successfully, but it still go through 3DS System. true: need go through 3DS System.

Payment Response Parameters

	Required	Format	Description
id(/payments)	Required	AN32[a-zA-Z0-9]32	The identifier of the payment request that can be used to reference the payment later. You get this as the field id of a payment's response.
registrationId	Required	AN32[a-zA-Z0-9]32	The identifier of the registration request that can be used to reference the registration later. You get this either as the field id of a registration's response or as the field registrationId of a payment's response (if the request contained createRegistration=true).
paymentBrand	Conditional	AN32[a-zA-Z0-9_] 32	The payment brand of the request.
amount	Conditional	N10.N2[0-9]10.[0-9]2	The amount of the request.
currency	Conditional	A3[a-zA-Z]3	The currency of the request.
descriptor	Conditional	AN127[\s\S]127	The descriptor of the request.
result.code	Required	AN11[0-9.]11	- The unique code that indicates the result status of the request. See the result codes for more detailed information.
result.description	Optional	AN255[\s\S]255	A textual description explaining the result.code's meaning.
result.avsResponse	Conditional	A1[A-Z]1	Contains the AVS response returned by the acquirer. It may include one the following result: A = Address does match, zip code does not match Z = Address does not match, zip code does match N = Address and zip code do not match U = Technical or logical error. AVS cannot be applied on card or address (not UK or US issuer), issuer is not available, etc. F = Address and Postal Code Matches
result.cvvResponse	Conditional	A1[A-Z]1	Contains the CVV response returned by the acquirer. It may include one the following result: M - CVV2 Match Indicates that the issuer was able to verify the CVV2 value provided by the merchant. N - CVV2, CVC2, Discover CID or AMEX CID do not match Indicates that the issuer was not able to verify the CVV2 value provided by the merchant. P - Not Processed Indicates that the issuer was unable to verify the CVV2 value provided by the merchant because either their verification system was not functioning, or not all of the information needed to verify the CVV2 value (such as the expiration date) was included in the request. S - CVV2, CVC2, Discover CID or AMEX CID data is not present on the card, but the issuer indicated it should be present Indicates that the issuer was unable to perform CVV2 verification, and notifies the merchant that the card should contain a CVV2 value. U - Unsupported by issuer or issuer is unable to process request Indicates that the issuer is not participating in the CVV2 service, or that the issue has not provided the card Brand with the required encryption keys needed to perform verification, or that STIP has responded with unavailable response.
result.macResponse	Optional	AN02	Merchant advice code from the acquirer. It may include one the following result: 01=New account information available 02=Cannot approve at this time, try again later 03=Do not try again 04=Token requirements not fulfilled for this token type 21=Payment Cancellation (Mastercard use only) 22=Merchant does not qualify for product code
resultDetails	Optional	AN2048[\s\S]2048	A container for name value pair used for enriching the response with bank-specific response details. I.e. the actual parameters used within resultDetails are bank-specific. Example: resultDetails.AuthCode=123456
resultDetails. AcquirerResponse	Conditional	AN2048[\s\S]2048	Represents the acquirer original response code retrieved from the acquirer directly.
card.bin	Optional	N6[\d]6	The first six digits of the card.number
card.holder	Optional	N6[\d]6	Holder of the credit card account
card.expiryMonth	Optional	N6[\d]2	The expiry month of the card
card.expiryYear	Optional	N4[\d]4	The expiry year of the card
merchant. bankAccount.holder	Required	AN128128	Holder of the merchant's bank account
merchant. bankAccount.number	Conditional	AN64[a-zA-Z0-9]64	The account number of the merchant's bank account. (IBAN for SEPA accounts)
merchant. bankAccount.bic	Conditional	AN11[a-zA-Z0-9]8	[a-zA-Z0-9]11
merchant. bankAccount.country	Conditional	AN2[a-zA-Z]2	The country code of the merchant's bank account (ISO 3166-1).

Other The response can also contain each of the data structures listed above, such as customer and billingAddress. n/a Conditional

	Required	Format	Description
buildNumber	Required	AN255[\s\S]255	Useful for support purposes.
timestamp	Required	date yyyy-MM-dd hh:mm:ssZ	The timestamp the response has generated.
ndc	Required	AN69[a-zA-Z0-9-]69	An internal unique identifier for the request.
additionalData	Conditional	AN255[\s\S]255	Additional Data from the bank acquiring system / card schemes: • TraceAuditNo :STAN, • EntryMode POS Entry Mode (01 for MOTO and 81 for E-commerce. For CP transaction, the field is same as request) • EntryMode POS Entry Mode (01 for MOTO and 81 for E-commerce. For CP transaction, the field is same as request) • EntryMode POS Entry Mode (01 for MOTO and 81 for E-commerce. For CP transaction, the field is same as request) • ConditionCode: POS condition code (00 for card present transaction, 08 means MOTO and 59 means E-commerce transaction) • RetrievalRefNo: Retrieval Reference number • AcquirerRefno: Acquirer Reference Number of the Transaction(23 digits) • RequestId: Unique Transaction Reference ID from CYBS

Payment

If you are fully PCI compliant, synchronous payment follow is recommended and asynchronous is also supported. In a synchronous workflow the payment data is sent directly in the server-to-server initial payment request and the payment is processed straight away.

If a customer pays with a card, a POST request is created over HTTPS to the baseUrl + resourcePath. The request should include all required information such as your authentication credentials, the type of transaction, the amount and the payment information such as card details. A payment request effectively combines a PA and capture request, automatically requesting that the funds are cleared if the authorization was successful.

resourcePath=/pay/v3/payments

curl http://host:port/pay/v3/payments \
  -d "entityId=tEntity1" \ 
  -d "entityType=PARTICIPATOR" \
  -d "amount=92.00" \
  -d "currency=CNY" \
  -d "paymentBrand=VISA" \
  -d "paymentType=DB" \
  -d "card.number=4200000000000000" \
  -d "card.holder=Jane Jones" \
  -d "card.expiryMonth=06" \
  -d "card.expiryYear=2020" \
  -d "merchantTransactionId=2020020asd30050044" \
  -H "Authorization: Bearer OGE4Mjk0MTc0YjdlY2IyODAxNGI5Njk5MjIwMDE1Y2N8c3k2S0pzVDg="

curl http://host:port/pay/v3/payments \
  -d "entityId=tEntity1" \ 
  -d "entityType=PARTICIPATOR" \
  -d "amount=50.00" \
  -d "currency=CNY" \
  -d "paymentBrand=VISA" \
  -d "paymentType=DB" \
  -d "card.token=23fg542983darr32fhsfs411isfgsr34q" \
  -d "merchantTransactionId=20220201asd254211" \
  -H "Authorization: Bearer OGE4Mjk0MTc0YjdlY2IyODAxNGI5Njk5Mj2345234sfg5ewgff145ad="

Once a payment is done, you will get a response from Eastpay payment Gateway.

{
  "id":"8ac7a4a27706b4b401770a6d346c0ff0",
  "paymentType":"DB",
  "paymentBrand":"VISA",
  "amount":"92.00",
  "currency":"EUR",
  "result":{
    "code":"000.000.000",
    "description":"Transaction successfully proceeded"
  },
  "resultDetails":{
    "clearingInstituteName":"EastPay"
  },
  "card":{
    "bin":"420000",
    "last4Digits":"0000",
    "holder":"Jane Jones",
    "expiryMonth":"05",
    "expiryYear":"2034"
  },
  "buildNumber":"5a76591c8e1d872b883720a8d9d82d2bc1ff8199@2020-01-15 07:59:05 +0000",
  "timestamp":"2020-01-16 09:01:05.208+0000",
  "ndc":"8a8294174b7ecb28014b9699220015ca_71665329ea9642e19b409bb793a9b80f"
}

Preauthorization

A Preauthorization is created by sending a POST request over HTTPS to baseUrl + resourcePath. The request should include all required information such as your authentication credentials, the type of transaction, the amount and the payment information such as card details. A capture may be sent against a successful PA to request that the funds are sent for clearing. 

resourcePath=/pay/v3/payments

curl http://host:port/pay/v3/payments \
  -d "entityId= Entity1" \ 
  -d "entityType=PARTICIPATOR" \
  -d "amount=92.00" \
  -d "currency=CNY" \
  -d "paymentBrand=MASTER" \
  -d "paymentType=PA" \
  -d "card.number=5454545454545454" \
  -d "card.holder=Jane Jones" \
  -d "card.expiryMonth=06" \
  -d "card.expiryYear=2020" \
  -d "card.cvv=123" \
  -d "merchantTransactionId=2020020asd30051122" \
  -H "Authorization: Bearer OGE4Mjk0MTc0YjdlY2IyODAxNGI5Njk5MjIwMDE1Y2N8c3k2S0pzVDg="

The sample response is the following

{
  "id":"8ac7a4a07706b4b301770a1ac39444bc",
  "paymentType":"PA",
  "paymentBrand":"",
  "amount":"92.00",
  "currency":"EUR",
  "descriptor":"1910.4169.5658 OPP_Channel ",
  "result":{
    "code":"000.000.000",
    "description":"Transaction successfully proceeded"
  },
  "resultDetails":{
    "clearingInstituteName":"EastPay"
  },
  "card":{
    "bin":"545454",
    "last4Digits":"5454",
    "holder":"Jane Jones",
    "expiryMonth":"05",
    "expiryYear":"2034"
  },
   "buildNumber":"5a76591c8e1d872b883720a8d9d82d2bc1ff8199@2020-01-15 07:59:05 +0000",
  "timestamp":"2020-01-16 07:31:02.325+0000",
  "ndc":"8a8294174b7ecb28014b9699220015ca_9e961b25b9f64108ac0e7fb3bf690e48"
}

Capture

A capture is used to request clearing for previously authorized funds. A capture request is performed against a previous preauthorization (PA) payment by referencing its payment.id. Captures can be for full or partial amounts and multiple capture requests against the same PA are allowed.

resourcePath=/pay/v3/payments/

curl http://host:port/pay/v3/payments /{id}\
  -d "entityId= tEntity1" \ 
  -d "entityType=PARTICIPATOR" \
  -d "paymentType=CP" \
  -d "amount=92.00" \
  -d "currency=CNY" \
  -d "originalTransactionId=123123123" \
  -d "merchantTransactionId= 202001160848001120000" \
  -H "Authorization: Bearer OGE4Mjk0MTc0YjdlY2IyODAxNGI5Njk5MjIwMDE1Y2N8c3k2S0pzVDg="

Response Sample:

{
  "id":"8ac7a4a07706b4b301770a61d9af08bc",
  "referencedId":"8ac7a4a07706b4b301770a61818707f5",
  "paymentType":"CP",
  "result":{
    "code":"700.400.100",
    "description":"cannot capture (PA value exceeded)"
  },
  "buildNumber":"5a76591c8e1d872b883720a8d9d82d2bc1ff8199@2020-01-15 07:59:05 +0000",
  "timestamp":"2020-01-16 08:48:40.879+0000",
  "ndc":"8a8294174b7ecb28014b9699220015ca_a4feddf631c74928b5d9c68d38916862"
}

Reversal

A reversal is performed against a previous payment, referencing its payment.id. A reversal can be sent against debit (DB) or preauthorization (PA) payment types.

Parameters

	Required	Format	Description
transactionSource	Optional	AN32[a-zA-Z0-9_]32	Used to indicate the type of reversal. CARDHOLDER: The reversal is initiated by cardholder. Usually it is a VOID transaction.ERROR: If the original transaction encounters a failure, this reason is used to initiate a reversal. PARTIAL: For partial reversal , please use this source type and send the reversal amount in referral request. SUSPECT: The reversal is caused by the suspected fraud TIMEOUT: The response received late of the original transaction.

resourcePath=/pay/v21/payments

curl http://host:port/pay/v3/payments \
  -d "entityId= tEntity1" \ 
  -d"entityType=PARTICIPATOR" \
  -d "paymentType=RV" \
  -d "originalTransactionId=123123123" \
  -d "merchantTransactionId=2020020asd30051234" \
  -H "Authorization: Bearer OGE4Mjk0MTc0YjdlY2IyODAxNGI5Njk5MjIwMDE1Y2N8c3k2S0pzVDg="

Request Response

{
  "id":"8ac7a4a27706b4b401770a70528d1225",
  "referencedId":"8ac7a4a27706b4b401770a6d346c0ff0",
  "paymentType":"RV",
  "result":{
    "code":"700.400.300",
    "description":"cannot reverse (already refunded|reversed, invalid workflow or amount exceeded)"
  },
  "buildNumber":"5a76591c8e1d872b883720a8d9d82d2bc1ff8199@2020-01-15 07:59:05 +0000",
  "timestamp":"2020-01-16 09:04:29.325+0000",
  "ndc":"8a8294174b7ecb28014b9699220015ca_1eb84f93b76741518e2ac16d3d047983"
}

Inquiry

Transaction inquiry using merchantTransaction ID

curl -G https://host:port/pay/v3/payments/{transaction.id} \
  -d "entityId= tEntity1" \ 
  -d "entityType=PARTICIPATOR" \ 
  -d "merchantTransactionId=test123" \
  -H "Authorization: Bearer OGE4Mjk0MTc0YjdlY2IyODAxNGI5Njk5MjIwMDE1Y2N8c3k2S0pzVDg="

The Sample response is

{
  "result":{
    "code":"000.000.100",
    "description":"successful request"
  },
  "buildNumber":"891f0b23df90eace0edc0f2010d685f7d60133dc@2021-01-28 11:06:16 +0000",
  "timestamp":"2021-01-29 10:52:45+0000",
  "ndc":"8a8294174b7ecb28014b9699220015ca_bfdfa7ca8d4049bda46d01bad02e69b0",
  "id":"8ac7a4a0673bd9e40167415ff34c7c9a",
  "referencedId":"8ac7a4a1673bc79501674152b57b3d11",
  "paymentType":"RC",
  "paymentBrand":"MC",
  "amount":"100.12",
  "currency":"EUR",
  "merchantMemo":"",
  "merchantTransactionId":"test123",
  "result":{
    "code":"000.000.000",
    "description":"Request successfully processed"
  },
  "customer":{
    "givenName":"Test",
    "surname":"User",
    "email":"nomad._1184002955_per@gmail.com"
  },
  "billing":{
    "street1":"1 Main St 1 Main St 2",
    "city":"San Jose",
    "state":"CA",
    "postcode":"95131",
    "country":"US"
  },
  "customParameters":{
    "INFO_matchingAlgorithm":"MANUAL_MATCH"
  },
  "timestamp":"2020-11-23 16:21:06.558+0000",
  "virtualAccount":{
    "accountId":"nomad._1184002955_per@gmail.com",
    "holder":"Test User"
  }
}

Refund

A refund is performed against a previous payment, referencing its payment.id by sending a POST request. A refund can be performed against Payment (DB) or captured preauthorization (PA->CP) payment types. Where supported, the amount field can be used to process a partial or full amount.

resourcePath=/pay/v3/payments

curl http://host:port/pay/v3/payments/{id}\
  -d "entityId=8a8294174b7ecb28014b9699220015ca" \
  -d "amount=10.00" \
  -d "currency=EUR" \
  -d "paymentType=RF" \
  -d "originalTransactionId=123123123" \
  -d "merchantTransactionId=2020020asd30050044" \
  -H "Authorization: Bearer OGE4Mjk0MTc0YjdlY2IyODAxNGI5Njk5MjIwMDE1Y2N8c3k2S0pzVDg="

Response Sample:

{
  "id":"8ac7a4a07706b4b301770a782eb924c1",
  "referencedId":"8ac7a49f7706aa4d01770a77b65058c8",
  "paymentType":"RF",
  "result":{
    "code":"700.400.520",
    "description":"refund needs at least one successful transaction of type (CP or DB)"
  },
  "buildNumber":"5a76591c8e1d872b883720a8d9d82d2bc1ff8199@2020-01-15 07:59:05 +0000",
  "timestamp":"2020-01-16 09:13:04.442+0000",
  "ndc":"8a8294174b7ecb28014b9699220015ca_0c8eeebd4f6940e8a246116d6bfbc1c7"
}

3D-Secure Transaction

3DS2 Information

For users who are integrating via server to server will need to prepare your front-end and back-end and send the following additional information along with the payment information :

Parameters

Field	API Field name	Description	Length/Format/Values
Accept header	customer.browser. acceptHeader	HTTP accept header sent from the cardholder's browser.	Length: Variable, maximum 2048 characters JSON Data Type: String Value accepted: If the total length of the accept header sent by the browser exceeds 2048 characters, the 3DS Server truncates
Language	customer.browser. language	The cardholder's browser language.	Length: Variable, 1–8 characters JSON Data Type: String
Screen height	customer.browser. screenHeight	This field contains the total height of the cardholder's screen in pixels.	Length: Variable, 1–6 characters JSON Data Type: String
Screen width	customer.browser. screenWidth	This field contains the total width of the cardholder's screen in pixels.	Length: Variable, 1–6 characters JSON Data Type: String
Browser timezone	customer.browser. timezone	This field contains the cardholder's browser local timezone.	Length: 1–5 characters JSON Data Type: String Value accepted: Value is returned from the getTimezoneOffset() method.
User agent	customer.browser. userAgent	This field contains the exact content of the HTTP User-Agent header.	Length: Variable, maximum 2048 characters JSON Data Type: String Value accepted: Note: If the total length of the User-Agent sent by the browser exceeds 2048 characters, the 3DS Server truncates the excess portion.
IP address	customer.ip	IP address of the cardholder's browser.	Length: Variable, maximum 45 characters JSON Data Type: String Value accepted: IPv4 address is represented in the dotted decimal format of 4 sets of decimal numbers separated by dots. The decimal number in each and every set is in the range 0 to 255. Example IPv4 address: 1.12.123.255 IPv6 address is represented as eight groups of four hexadecimal digits, each group representing 16 bits (two octets. The groups are separated by colons (:). Example IPv6 address:2011:0db8:85 a3:0101:0101:8a2e:03 70:7334
Java enabled	customer.browser. javaEnabled	true/false - Ability of the cardholder's browser to execute Java.	JSON Data Type: Boolean Values accepted: • true • false
Javascript enabled	customer.browser. javascriptEnabled	true/false - Ability of the cardholder's browser to execute JavaScript	JSON Data Type: Boolean Values accepted: • true • false
Screen color depth	customer.browser. screenColorDepth	This field contains a value representing the bit depth of the color palette, in bits per pixel, for displaying images.	Length: 1–2 characters JSON Data Type: String Values accepted: 1 = 1 bit • 4 = 4 bits • 8 = 8 bits • 15 = 15 bits • 16 = 16 bits • 24 = 24 bits • 32 = 32 bits • 48 = 48 bits
Authentication window size	customer.browser. challengeWindow	Size of the authentication iframe which will render the ACS authentication front-end to the shopper for interaction.	Please send an Integer between 1-5. The integer corresponds to one the following resolutions:()

Reqeust and Response

• Send the request with 3DS information
• Handle Method Data and Method URL if issuer returned in an immediate response (optional step) ; If the issuer
• Receive the final response

After you sent the request with 3DS information , you will get an immediate response with Method Data and Method URL which returned by issuer. It is an optional step, but if it's returned it's important to handle it properly.

• Request Sample:

  authentication.entityId=8ac7a49f6e4a18ae016e4b8b4c4b2146
  amount=12.00
  currency=EUR
  paymentBrand=VISA
  paymentType=PA
  merchantTransactionId=order99234
  transactionCategory=EC
  card.number=4000000000000010
  card.expiryMonth=12
  card.expiryYear=2025
  card.cvv=123
  card.holder=John Smith
  merchant.name=MerchantCo
  merchant.city=Munich
  merchant.country=DE
  merchant.mcc=5399
  customer.ip=192.168.0.1
  customer.browser.acceptHeader=text/html
  customer.browser.screenColorDepth=48
  customer.browser.javaEnabled=false
  customer.browser.language=de
  customer.browser.screenHeight=1200
  customer.browser.screenWidth=1600
  customer.browser.timezone=60
  customer.browser.challengeWindow=4
  customer.browser.userAgent=Mozilla/4.0 (MSIE 6.0; Windows NT 5.0)
  shopperResultUrl="https://host:port/xxx"

• Get Optional Response with Method Data and Method URL:

  {
    "id": "8ac7a4a0686138d701687eebfbc74747",
    "paymentType": "DB",
    "paymentBrand": "VISA",
    "result": {
      "code": "000.200.000",
      "description": "transaction pending"
    },
    "resultDetails": {
      "clearingInstituteName": "CI_Test"
    },
    "card": {
      "bin": "411111",
      "last4Digits": "1111",
      "holder": "Jane Jones",
      "expiryMonth": "05",
      "expiryYear": "2020"
    },
    "redirect": {
      "url": "https://host:port/v3/threeDSecure/execute",
      "parameters": [{
        "name": "name",
        "value": "value"
      }],
    },
    "buildNumber": "deebd8c9af7d84ddee98c38b7f4afcc814012b5b@2019-01-22 13:58:00 +0000",
    "timestamp": "2019-01-24 08:13:41+0000",
    "ndc": "8a8294174b7ecb28014b9699220015ca_0557df43f75643d19479440642979e00"
  }

In immediate response , Method Data and Method URL are not always returned by the issuer. If your get Method Data and Method URL, you shouldRedirect the shopper within and iframe to the redirect URL if onload event received from 1.

<form name='' action='redirect.URL' method='POST'>
 <INPUT type='hidden' name='redirect.parameters[n].name' value='redirect.parameters[].value'>
</form>
<script>
 window.onload = submitForm;
 function submitForm() { downloadForm.submit(); }
</script>

Parameters:

	Required	Format	Description
redirect.url	Conditional	AN2048[\s\S]2048	URL the shopper must be redirected to in order to proceed.
redirect. parameters[n].name	Conditional	AN255[\s\S]255	List of parameter names for the redirect.url. The corresponding parameter value is the same parameter number ending with .value like described in the line below.
redirect. parameters[n].value	Conditional	AN255[\s\S]255	The parameter values corresponding to the names as described above.

• Get final response:

  shopperResultUrl in request will receive the final response.

  {
    "id":"8ac7a49f6e4a18ae016e4b8b4c4b2146",
    "paymentType":"PA",
    "paymentBrand":"VISA",
    "amount":"12.00",
    "currency":"EUR",
    "result":{
      "code":"000.100.112",
      "description":"Request successfully processed in 'Merchant in Connector Test Mode'"
    },
    "resultDetails":{
      "ExtendedDescription":"Approved",
      "AcquirerResponse":"00",
    },
    "card":{
      "bin":"400000",
      "last4Digits":"0044",
      "expiryMonth":"12",
      "expiryYear":"2025"
    },
    "threeDSecure":{
      "eci":"05",
      "verificationId":"MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=",
      "version":"2.1.0",
      "dsTransactionId":"91caca63-5c4e-4aa2-a3f1-b4d418972de8",
      "acsTransactionId":"7055d78e-eb35-46e7-8c4e-56e15092b5f5",
    },
    "buildNumber":"7810ceecdd913cd9c4807becb99b89ce68454900@2019-11-08 12:20:52 +0000",
    "timestamp":"2019-11-08 15:05:42+0000",
    "ndc":"8ac7a4c76dd857ea016dda2ea6970684_3ba4c7691f854354906b2f6c402840e7"
  }

Optional 3DS Information

Please note that in order to have a better rate of successful risk-checks during the risk based authentication, it is recommended to send as many fields as possible. This will positively affect the number of frictionless flows.

Parameters

Field name	Mandatory/Optional	Source when integrating via Server-to-Server API	Format, Length
billing.city	Required unless market or regional mandate restricts sending this information.	Cardholder (via API)	Length: Variable, 2–45 characters Format: String with values accepted indicated below
billing.country	Required unless market or regional mandate restricts sending this information.	Cardholder (via API)	Length: 2 characters Format: [A-Z]2
billing.street1	Required unless market or regional mandate restricts sending this information.	Cardholder (via API)	Length: Variable, maximum 50 characters Format: String
billing.postcode	Required unless market or regional mandate restricts sending this information.	Cardholder (via API)	Length: Variable, maximum 50 characters Format: String
customer.email	Required unless market or regional mandate restricts sending this information.	Cardholder (via API)	Length: Variable, maximum 128 characters Format: String
card.holder	Required unless market or regional mandate restricts sending this information.	Cardholder (via API)	Length: Variable, maximum 128 characters Format: String
amount	Mandatory	Payment (via API)	Length: Variable, maximum 12 characters Format: Numeric with 2 minor units after the decimal point Example: 123.00
currency	Mandatory	Payment (via API)	Length: 3 characters Format: ISO 4217 A3 currency code
shipping.city	Optional	Cardholder (via API)	Length: Variable, maximum 50 characters Format: String
shipping.country	Optional	Cardholder (via API)	Length: 3 characters Format: ISO 3166-1 A2 country code
shipping.street1	Optional	Cardholder (via API)	Length: Variable, maximum 50 characters Format: String
shipping.street2	Optional	Cardholder (via API)	Length: Variable, maximum 50 characters Format: String
shipping.postcode	Optional	Cardholder (via API)	Length: Variable, maximum 16 characters Format: String
shipping.state	Optional	Cardholder (via API)	Length: Variable: maximum 3 characters Format: Should be the country subdivision code defined in ISO 3166-2
billing.street2	Optional	Cardholder (via API)	Length: Variable, maximum 50 characters Format: String
billing.state	Optional	Cardholder (via API)	Length: Variable: maximum 3 characters Format: Should be the country subdivision code defined in ISO 3166-2
customer.phone	Optional	Cardholder (via API)	Length: Variable: maximum 20 characters Format: +ccc-nnnnnnnn Where: + sign is optional cc - country code, maximum 3 characters "-" - mandatory character nnnnnnnnnn - phone number without the country code, maximum 15 characters
customer.workPhone	Optional	Cardholder (via API)	Length: Variable: maximum 20 characters Format: +ccc-nnnnnnnn Where: + sign is optional cc - country code, maximum 3 characters "-" - mandatory character nnnnnnnnnn - phone number without the country code, maximum 15 characters
customer.mobile	Optional	Cardholder (via API)	Length: Variable: maximum 20 characters Format: +ccc-nnnnnnnn Where: + sign is optional cc - country code, maximum 3 characters "-" - mandatory character nnnnnnnnnn - phone number without the country code, maximum 15 characters
customer.browser. acceptHeader	Mandatory	Merchant should collect and send via API	Length: Variable, maximum 2048 characters Format: String
customer.browser. language	Mandatory	Merchant should collect and send via API	Length: Variable, 1–8 characters Format: String Returned from navigator.language property.
customer.browser. screenHeight	Mandatory when customer.browser. javascriptEnabled = true; otherwise Optional	Merchant should collect and send via API	Length: Variable, 1–6 Format: Numeric Value is returned from the screen.height property
customer.browser. screenWidth	Mandatory when customer.browser. javascriptEnabled = true; otherwise Optional	Merchant should collect and send via API	Length: Variable, 1–6 Format: Numeric Value is returned from the screen.width property
customer.browser. timezone	Mandatory when customer.browser. javascriptEnabled = true; otherwise Optional	Merchant should collect and send via API	Length: Variable, 1–5 characters Format: Numeric Value is returned from the getTimezoneOffset() method.
customer.browser. userAgent	Mandatory	Merchant should collect and send via API	Length: Variable, maximum 2048 characters Format: String
customer.ip	Optional	Merchant should collect and send via API	Length: Variable, maximum 45 characters Format: IPv4 address Example: 1.12.123.255
customer.browser. javaEnabled	3DS 2.1 : Mandatory 3DS 2.2: Mandatory when customer.browser. javascriptEnabled = true; otherwise Optional	Merchant should collect and send via API	Values accepted: • true • false Value is returned from the navigator.javaEnabled property.
customer.browser. javascriptEnabled	Mandatory	Merchant should collect and send via API	Values accepted: • true • false
customer.browser. screenColorDepth	3DS 2.1 : Mandatory 3DS 2.2: Mandatory when customer.browser. javascriptEnabled = true; otherwise Optional	Merchant should collect and send via API	Length: 1–2 characters Format: String Values accepted: • 1 = 1 bit • 4 = 4 bits • 8 = 8 bits • 15 = 15 bits • 16 = 16 bits • 24 = 24 bits • 32 = 32 bits • 48 = 48 bits
customer.browser. challengeWindow	Optional	Merchant should collect and send via API	Length: 2 characters Values accepted: • 01 = 250 x 400 • 02 = 390 x 400 • 03 = 500 x 600 • 04 = 600 x 400 • 05 = Full screen
threeDSecure.amount	Optional	Sent via the API	Length: Variable, maximum 12 characters Format: Numeric with 2 minor units after the decimal point Example: 123.00
threeDSecure.currency	Optional	Sent via the API	Length: 3 characters Format: ISO 4217 A3 currency code

Authentication Amount and Currency

In some cases the amount and/or currency that is used in the authentication can be different from the one that will be used in the payment later. For example the payment amount might not be known at the time of the authentication, or the merchant would like to authenticate the shopper for the full amount when the payment will be done in multiple installments.

If the authentication amount and the payment amount are different, then the authentication amount and currency can be sent in a separate fields:

feild	desc
threeDSecure.amount	Amount for which the shopper will be authenticated for.
threeDSecure.currency	Currency for which the shopper will be authenticated for.

Please note that payment amount and currency are still mandatory fields for any payment request. If there are no authentication amount and currency defined then the shopper will be authenticated with the payment amount and currency.

Optional Setting

Challenge Indicator

Merchants have the possibility to set the preference of a transaction being challenged or not. This really is only a preference, and won't guarantee that the issuer will or will not request a challenge from the cardholder. It is up to the issuer if they consider the merchant's preference, and if they include it when they assess the risk of the transaction.

For example when a card is being stored for later use (e.g. for One click checkout), a challenge may be requested by the merchant. In another example, there might be some regional mandates that certain transactions have to be challenged and the merchant should ask for a mandated challenge.

Send the field threeDSecure.challengeIndicator with one of the following values:

Value Challenge Preference Description

Value	Challenge Preference	Description
01	No preference	The merchant has no preference, and fully trust the issuer to ask a challenge from the cardholder.
02	No challenge requested	The merchant prefers that the cardholder is not authenticated by the issuer, and only the frictionless flow applies
03	Challenge requested: 3D Secure Requestor Preference	The merchant prefers that the cardholder is authenticated by the issuer.
04	Challenge requested: Mandate	The cardholder authentication is mandated (e.g. by regional mandates)

The field threeDSecure.challengeIndicator is optional. If not sent, the value "01 - No preference" applies by default.

Cardholder history with merchant

The following fields are not mandatory, but it is strongly recommended to send them. They are affecting the accuracy of the issuer's risk check, and will result in more frictionless flows.

Parameters

customParameters[ReqAuthMethod]

• Method used by the Cardholder to authenticate to the 3D Secure Requestor. Contains optional information about how the cardholder authenticated during login to their 3D Secure Requestor account. Possible values are:
  • 01 No authentication occurred (i.e. cardholder "logged in" as guest)
  • 02 Login to the cardholder account at the merchant system using cardholder's own credentials
  • 03 Login to the cardholder account at the merchant system using federated ID
  • 04 Login to the cardholder account at the merchant system using issuer credentials
  • 05 Login to the cardholder account at the merchant system using third-party authentication
  • 06 Login to the cardholder account at the merchant system using FIDO Authenticator

customParameters[ReqAuthTimestamp]

• Date and time in UTC of the cardholder authentication. Accepted date format is YYYYMMDDHHMM. Part of the 3D Secure Requestor Authentication Information which contains optional information about how the cardholder authenticated during login to their account.

customParameters[PriorAuthMethod]

• Mechanism used by the Cardholder to previously authenticate to the 3D Secure Requestor. Contains information about a 3D Secure cardholder authentication that occurred prior to the current transaction. Possible values are:
  • 01 Frictionless authentication occurred by ACS
  • 02 Cardholder challenge occurred by ACS
  • 03 ACS verified
  • 04 Other issuer methods

customParameters[PriorAuthTimestamp]

• Date and time in UTC of the prior cardholder authentication. Accepted date format is YYYYMMDDHHMM. Contains information about a 3D Secure cardholder authentication that occurred prior to the current transaction.

customParameters[PriorReference]

• This data element provides additional information to the ACS to determine the best approach for handling a request. It contains an ACS Transaction ID for a prior authenticated transaction (for example, the first recurring transaction that was authenticated with the cardholder).
• Contains information about a 3D Secure cardholder authentication that occurred prior to the current transaction.

customParameters[AccountId]

• Additional information about the account optionally provided by the 3D Secure Requestor in AReq messages.

customParameters[AccountAgeIndicator]

• Length of time that the cardholder has had the account with the 3D Secure Requestor. Possible values are:
  • 01 No account (guest check-out)
  • 02 Created during this transaction
  • 03 Less than 30 days
  • 04 30-60 days
  • 05 More than 60 days

customParameters[AccountChangeDate]

• Date that the cardholder's account with the 3D Secure Requestor was last changed. Accepted date format is YYYYMMDD.

customParameters[AccountChangeIndicator]

• Length of time since the cardholder's account information with the 3D Secure Requestor was last changed. Possible values are:
  • 01 Created during this transaction
  • 02 Less than 30 days
  • 03 30-60 days
  • 04 More than 60 days

customParameters[AccountDate]

• Date that the cardholder opened the account with the 3D Secure Requestor. Accepted date format is YYYYMMDD.

customParameters[AccountPasswordChangeDate]

• Date that cardholder's account with the 3D Secure Requestor had a password change or account reset. Accepted date format is YYYYMMDD.

customParameters[AccountPasswordChangeIndicator]

• Indicates the length of time since the cardholder's account with the 3D Secure Requestor had a password change or account reset. Possible values are:
  • 01 No account (guest check-out)
  • 02 Created during this transaction
  • 03 Less than 30 days
  • 04 30-60 days
  • 05 More than 60 days

customParameters[AccountPurchaseCount]

• Number of purchases with this cardholder account during the previous six months.

customParameters[AccountProvisioningAttempts]

• Number of Add Card attempts for the account in the last 24 hours.

customParameters[AccountDayTransactions]

• Number of transactions (successful and abandoned) for this cardholder account with the 3D Secure Requestor across all ayment accounts in the previous 24 hours.

customParameters[AccountYearTransactions]

• Number of transactions (successful and abandoned) for this cardholder account with the 3D Secure Requestor across all payment accounts in the previous year.

customParameters[PaymentAccountAge]

• Date that the payment account was enrolled in the cardholder's account with the 3D Secure Requestor. Accepted date format is YYYYMMDD.

customParameters[PaymentAccountAgeIndicator]

• Indicates the length of time that the payment account was enrolled in the cardholder's account with the 3D Secure Requestor. Possible values are:
  • 01 No account (guest check-out)
  • 02 Created during this transaction
  • 03 Less than 30 days
  • 04 30-60 days
  • 05 More than 60 days

customParameters[ShipAddressUsageDate]

• Date when the shipping address used for this transaction was first used with the 3D Secure Requestor. Accepted date format is YYYYMMDD.

customParameters[ShipAddressUsageIndicator]

• Indicates the length of time since the shipping address used for this transaction was first used with the 3D Secure Requestor. Possible values are:
  • 01 No account (guest check-out)
  • 02 Created during this transaction
  • 03 Less than 30 days
  • 04 30-60 days
  • 05 More than 60 days

customParameters[ShipIndicator]

• Indicates shipping method chosen for the transaction. Merchants must choose the Shipping Indicator code that most accurately describes the cardholder's specific transaction, not their general business. If one or more items are included in the sale, the Shipping Indicator code for the physical goods is used, or if all digital goods, the Shipping Indicator code that describes the most expensive item. Possible values are:
  • 01 Ship to cardholder's billing address
  • 02 Ship to another verified address on file with merchant
  • 03 Ship to address that is different than the cardholder's billing address
  • 04 "Ship to Store" / Pick-up at local store (Store address shall be populated in shipping address fields)
  • 05 Digital goods (includes online services, electronic gift cards and redemption codes)
  • 06 Travel and Event tickets, not shipped
  • 07 Other (for example, Gaming, digital services not shipped, emedia subscriptions, etc.)

customParameters[ShipNameIndicator]

• Indicates if the Cardholder Name on the account is identical to the shipping Name used for this transaction. Possible values are:
  • 01 Account Name identical to shipping Name
  • 02 Account Name different than shipping Name

customParameters[SuspiciousAccountActivity]

• Indicates whether the 3D Secure Requestor has experienced suspicious activity (including previous fraud) on the cardholder account. Possible values are:
  • 01 No suspicious activity has been observed
  • 02 Suspicious activity has been observed

customParameters[TransactionType]

• Identifies the type of transaction being authenticated. Possible values are:
  • 01 Goods / Service Purchase
  • 03 Check Acceptance
  • 10 Account Funding
  • 11 Quasi-Cash Transaction
  • 28 Prepaid Activation and Load

customParameters[DeliveryTimeframe]

• Indicates the merchandise delivery timeframe. Possible values are:
  • 01 Electronic Delivery
  • 02 Same Day Shipping
  • 03 Overnight Shipping
  • 04 Two-day or more shipping

customParameters[DeliveryEmailAddress]

• For Electronic delivery, the email address to which the merchandise was delivered.

customParameters[ReorderItemsIndicator]

• Indicates whether the cardholder is reordering previously purchased merchandise. Possible values are:
  • 01 First time ordered
  • 02 Reordered

customParameters[PreOrderPurchaseIndicator]

• Indicates whether Cardholder is placing an order for merchandise with a future availability or release date. Possible values are:
  • 01 Merchandise available
  • 02 Future availability

customParameters[PreOrderDate]

• For a pre-ordered purchase, the expected date that the merchandise will be available.
• Date format = YYYYMMDD

customParameters[GiftCardAmount]

• For prepaid or gift card purchase, the purchase amount total of prepaid or gift card(s) in major units (for example, USD 123.45 is 123).

customParameters[GiftCardCurrency]

• For prepaid or gift card purchase, ISO 4217 three-digit currency code of the gift card.

customParameters[GiftCardCount]

• For prepaid or gift card purchase, total count of individual prepaid or gift cards/codes purchased.

Submit a Pre-Authenticated Payment Request

If you have used an external 3DS MPI to authenticate the payer, then you must pass information about the authentication in payment request. Please set threeDSeucre.indicator=third. And if 3DS authentication fails, below information is not available. It is recommended not to send this group of information with failed authentication.

Parameters

	Required	Format	Description
threeDSecure. indicator		AN2048	The indicator will be ignored if the merchant 3DS authentication is not optional. force: The transaction need go through Risk System (such as DM), although it go through Risk System successfully, but it still go through 3DS System. true: need go through 3DS System. third: If you will provide pre-authenticated information Mandatory
threeDSecure. authenticationStatus	Mandatory	AN(1)	Indicates the result of payer authentication with the issuer.
threeDSecure.eci	Mandatory	N2	The Electronic Commerce Indicator that is returned to you in the authentication response message.
threeDSecure. verificationId	Mandatory		The base64 encoded value generated by the card issuer that is returned to you in the authentication response message
threeDSecure. dsTransactionId	Mandatory		A unique transaction identifier generated for the 3DS authentication. This field corresponds to the identifier assigned by the scheme directory server.

Optional Information

Risk Screening Indicator

Request parameters

	Required	Format	Description
risk.ind	Optional	AN1	Risk Indicator
risk.systemID	Conditional	AN32[\s\S] 32	- Risk System ID : CYBSDM、 ACIRS、 INTERNAL

Response parameters

	Required	Format	Description
risk.score	Optional	AN32	Risk Score from Risk system
risk.decision	Conditional	AN32[\s\S] 32	Decision from Risk system: DECLINE、ACCEPT、 CHALLENGE

Customer Information

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.

Parameters

	Required	Format	Description
customer. merchantCustomerId	Conditional	AN100[\s\S]100	An identifier for this customer. Typically this is the ID that identifies the shopper in the shop's system.
customer.givenName	Conditional	AN48[\s\S]48	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
customer.middleName	Optional	AN48[\s\S]48	The middle name of the customer.
customer.surname	Conditional	AN[\s\S]48	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
customer.sex	Optional	M|F	Sex of the shopper, 'M' for male or 'F' for female A1
customer.birthDate	Conditional	AN10 {19|20)([0-9]2)-(0[1-9]|1[0-2])-(0[1-9]|1[0-9]|2[0-9]|3[0-1]}	The birth day of the customer in the format yyyy-MM-dd, e.g. 1970-02-17
customer.phone	Optional	AN15[+0-9][0-9 .()/-]25	The customer's phone number. Required for some risk checks.
customer.mobile	Optional	AN25[+0-9][0-9 .()/-]25	The customer's mobile number. Required for some risk checks.
customer.workPhone	Optional	AN25[\s\S]25	The customer's phone number. Required for some risk checks.
customer.email	Optional	AN128[\s\S]128	The customer's email address. Required for some risk checks and transmission of direct debit mandates.
customer.companyName	Optional	AN60[\s\S]60	The customer's company name.
customer. identificationDocType	Conditional	A12[\s\S]	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).
customer. identificationDocId	Conditional	AN64[\s\S]64	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).
customer.ip	Optional	AN255[\s\S]255	The customer's IP address.
customer. browserFingerprint.id	Optional	[\s\S]255	The reference to the fingerprint of the shopper's browser, in most cases provided by some JavaScript library.
customer. browserFingerprint.value	Optional	[\s\S]4096	The actual fingerprint value of the shopper's browser
customer.browser. acceptHeader	Conditional	[\s\S]2048	Exact content of the HTTP accept headers as sent to the 3DS Requestor from the Cardholder’s browser. Mandatory for 3DS v2.
customer.browser. language	Conditional	[\s\S]8	Value representing the browser language as defined in IETF BCP47. Returned from navigator.language property. Mandatory for 3DS v2.
customer.browser. screenHeight	Conditional	[\s\S]6	Total height of the Cardholder’s screen in pixels. Value is returned from the screen.height property. Mandatory for 3DS v2.
customer.browser. screenWidth	Conditional	[\s\S]6	Total width of the Cardholder’s screen in pixels. Value is returned from the screen.width property. Mandatory for 3DS v2.
customer.browser. timezone	Conditional	[\s\S]5	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.
customer.browser. userAgent	Conditional	[\s\S]2048	Exact content of the HTTP user-agent header. Mandatory for 3DS v2.
customer.browser. javaEnabled	Conditional	true/false	Boolean that represents the ability of the cardholder browser to execute Java. Value is returned from the navigator.javaEnabled property. Mandatory for 3DS v2.
customer.browser. screenColorDepth	Optional	N2[0-9]2	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.
customer.browser. challengeWindow	Optional	N2	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.
customer.browser. deviceId	Optional	AN32[\s\S]32	Value representing the customer browser device id.
customer.status	Optional	A9[\s\S]255	A status of the customer. Currently two options- NEW, EXISTING.

Shipping Customer

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

Parameters

	Required	Format	Description
shipping.customer.*	Optional		All the fields that are available under customer except shipping.customer.browserFingerprint.* and shipping.customer.browser.deviceId Same as for customer fields

Billing Address

The billing address holds the address of the customer. Information sent in the billing address data structure can optionally be used for risk checks such as AVS for card processing.

It is recommended to send ASCII characters for address information.

EastPay accepts and stores non-ASCII characters correctly and displays them correctly in reports, but non-ASCII may affect address verification results.

Parameters

	Required	Format	Description
billing.street1	Conditional	AN100[\s\S]100	The door number, floor, building number, building name, and/or street name of the billing address Mandatory for 3D Secure v2.
billing.street2	Conditional	AN100[\s\S]100	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.
billing. houseNumber1	Optional	AN100[\s\S]100	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.
billing. houseNumber2	Optional	AN100[\s\S]100	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.
billing.city	Conditional	AN48[\s\S]48	The town, district or city of the billing address Mandatory for 3D Secure v2.
billing.state	Conditional	AN10[a-zA-Z0-9.]10	The county, state or region of the billing address
billing.postcode	Conditional	AN10[A-Za-z0-9]10	The postal code or zip code of the billing address Mandatory for 3D Secure v2.
billing.country	Conditional	A2[A-Z]2	The country of the billing address (ISO 3166-1) Mandatory for 3D Secure v2.
billing.normalized	Optional	AN255[\s\S]255	The normalized shipping address.
billing. validationStatus	Optional	AN255[\s\S]255	Indicates whether a address got validated and normalized address got confirmed by the consumer

Shipping Address

The shipping address holds the location and recipient of ordered goods. This can be used for risk processing or logistics.

Parameters

	Required	Format	Description
shipping.street1	Conditional	AN100[\s\S]100	The door number, floor, building number, building name, and/or street name of the shipping address
shipping.street2	Conditional	AN100[\s\S]100	The adjoining road or locality (if required) of the shipping address
shipping. houseNumber1	Optional	AN100[\s\S]100	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.
shipping. houseNumber2	Optional	AN100[\s\S]100	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.
shipping.city	Conditional	AN50[a-zA-Z]50	The town, district or city of the shipping address
shipping.state	Conditional	AN10[a-zA-Z0-9.]10	The county, state or region of the shipping address
shipping.postcode	Conditional	AN10[A-Za-z0-9]10	The postal code or zip code of the shipping address
shipping.country	Conditional	A2[A-Z]2	The country of the shipping address (ISO 3166-1)
shipping. destinationType	Optional	AN20[A-Za-z0-9]20	Shipping destination of item. Example: Commercial, Residential, Store
shipping. destinationCode			Indicates destination chosen for the transaction. Possible values: 01- Ship to cardholder billing address 02- Ship to another verified address on file with merchant 03- Ship to address that is different than billing address 04- Ship to store (store address should be populated on request) 05- Digital goods 06- Travel and event tickets, not shipped 07- Other AN2 Optional
shipping.method	Conditional	AN30[a-	z_]30
shipping.cost	Conditional	N13[0-9]10.[0-9]2	Total hipping cost
shipping.comment	Conditional	AN160[\s\S]160	A comment for the shipping
shipping. expectedDate	Optional	AN10{19|20)([0-9]2)-(0[1-9]|1[0-2])-(0[1-9]|1[0-9]|2[0-9]|3[0-1]}	The expected delivery date
shipping. logisticsProvider	Optional	AN255[\s\S]255	The logistics provider of the shipping
shipping. trackingNumber	Optional	AN255[\s\S]255	The tracking number of the shipping
shipping. returnTrackingNumber	Optional	AN255[\s\S]255	The tracking number issued for returns
shipping. normalized	Optional	AN255[\s\S]255	The normalized shipping address.
shipping. validationStatus	Optional	AN255[\s\S]255	Indicates whether a address got validated and normalized address got confirmed by the consumer
shipping. warehouse	Optional	AN100[\s\S]100	The warehouse that fulfilled the order
shipping. preference	Optional	AN21 GET_FROM_FILE NO_SHIPPING SET_PROVIDED_ADDRESS	Indicates the shipping preference. Possible values: GET_FROM_FILE | use the shipping address provided by customer at acquirer hosted pages. NO_SHIPPING | no shipping is expected for the purchase. Preferred option for digital goods. SET_PROVIDED_ADDRESS use the merchant provided address. The customer can't change this address on the acquirer hosted pages. Default value: GET_FROM_FILE

Merchant

The merchant data structure can be used to override the information that is shown on the cardholder statement. It can also be used for payment facilitators.

Parameters

	Required	Format	Description
merchant.name	Mandatory	AN100[\s\S]100	The registration name of the merchant.
merchant.business	Mandatory	AN22[\s\S]22	The name of the merchant. It will normally make up the first line of the card holder statement.
merchant.website	Optional	AN100[\s\S]100	This normally makes up the second line of the card holder statement.
merchant.street	Mandatory	AN100[\s\S]100	The door number, floor, building number, building name, and/or street name of the merchant
merchant.postcode	Mandatory	AN10[A-Za-z0-9-]10	The postal code or zip code of the merchant
merchant.city	Mandatory	AN50[a-zA-Z0-9]50	The city of the merchant
merchant.state	Mandatory	AN50[a-zA-Z0-9]50	The county, state or region of the merchant
merchant.country	Mandatory	A2[A-Za-z]2	The country of the merchant
merchant.phone	Optional	AN25[a-zA-Z0-9+-.]25	The merchant's phone number.
merchant.mmcc	Mandatory	AN4[0-9]4	The merchant's category code (Mastercard).
merchant.vmcc	Mandatory	AN4[0-9]4	The merchant's category code (Visa).
merchant.pfId	Optional	AN11[\s\S]11	The Payment Facilitators if of the merchant
merchant.isoId	Optional	AN8[\s\S]11	The Independent Sales Organization of the merchant
merchant.submerchantId	Optional	AN15[\s\S]100	The id of the sub-merchant of the payment facilitator.

Card on File

Following are all the parameters needed for sending card on file transactions.

Parameters

	Required	Format	Description
standingInstruction. type	Optional	UNSCHEDULED , INSTALLMENT,RECURRING	The category of the transaction. RECURRING: Recurring Transactions are transactions that are processed on a regular fixed interval for a pre-agreed or advised amount, where applicable. Recurring Transactions don't have a fixed duration and will continue to be processed until the cardholder cancels the agreement. INSTALLMENT: Installment Payments are transactions that are processed on a regular fixed interval for a pre-agreed amount for a single purchase of good or services. Unlike Recurring Transactions, Installment Payments do have a fixed duration and shouldn't continue to be processed after the end of the agreed installment period. UNSCHEDULED: An unscheduled credential-on-file transaction is like a recurring transaction but differs in that it does not happen at pre-agreed intervals. The classic example of such a transaction is when it is triggered by an event such as an amount threshold to ensure that a pay-as-you-go account always has a minimum available reserve.
standingInstruction. mode	Optional	INITIAL ,REPEATED	Indicating the mode of subsequent payment transaction. INITIAL: The payment is the first of a series of payments. This first payment must contain additional data like the CVV code or 3D parameters to enable an initial authentication of the request. REPEATED: The payment is a subsequent payment. It may not contain shopper authentication data like the CVV code or 3D parameters - the shopper is not present anymore.
standingInstruction. source	Conditional	AN	Indicating the type of subsequent payment transaction. CIT: Cardholder initiated transaction. MIT: Merchant initiated transaction.
standingInstruction. initialTransactionId	Optional	(No specific format-Depends on acquirer)	The value/ID is received as part of the acquirer response of a CIT flagged transaction. The ID is received in OPP response field: standingInstruction.initialTransactionId. The ID must be included in all following MIT flagged transaction. AN or N
standingInstruction. industryPractice	Optional	INCREMENTAL_AUTH, RESUBMISSION, REAUTHORIZATION, DELAYED_CHARGES ,NO_SHOW	The MIT types defined under this category are performed to fulfill a business practice as a follow-up to an original cardholder-merchant interaction that could not be completed with one single transaction. INCREMENTAL_AUTH: Incremental authorizations can be used to increase the total amount authorized. Incremental authorizations do not replace the original authorization — they are additional to previously authorized amounts — the sum of all linked estimated and incremental authorizations represent the total amount on hold in the cardholder’s account for a given transaction. RESUBMISSION: When a merchant attempts to authorize a transaction after the service has been used but the issuer declines it for insufficient funds, they may attempt to re-authorize to recover the debt. These authorization requests are considered resubmission authorizations and must carry the new "re submission" indicator. REAUTHORIZATION: Re-authorization occurs when a merchant has a need to submit an authorization request after the cardholder has left the point of interaction and there is no possibility of re-authenticating the card or the cardholder. A merchant may need to do this if they intend to split the shipment into multiple deliveries and will only authorize as goods come into stock. If the need to re-authorize occurs, the subsequent authorization requests carry the new "re-authorization" marker and the scheme reference data from the initial interaction. DELAYED_CHARGES and NO_SHOW: Such transactions occur largely in the rental and hospitality sectors. These transactions also carry the scheme reference data provided in the initial authorization at the start of the rental or stay agreement as well as in the settlement record.
standingInstruction. expiry	Conditional / Mandatory when processing 3D Secure on recurring /installment.	yyyy-MM-dd	Recurring Expiry: Date after which no further authorizations shall be performed. Recurring transaction. Installment transaction.
standingInstruction. frequency	Conditional / Mandatory when processing 3D Secure on recurring /installment.	N4	Recurring Frequency: Indicates the minimum number of days between authorisations. Recurring transaction. Installment transaction. Integer value indicating the minimum number of days between recurring authorizations. A frequencyof monthly is indicated by the value 28. Multiple of 28 days will be used to indicate months. Example: 6 months = 168, Example values accepted (31 days): 31, 031, 0031. Note This field is required for recurring transactions
standingInstruction. numberOfInstallments	Conditinoal	N3	Installment Payment Data: Indicates the maximum number of authorisations permitted for installment payments.

Order Information

Contains detailed order-level information.

Parameters

	Required	Format	Description
order.totalAmount	Conditional	N10.N2[0-9]10(.[0-9]2)?	Grand total for the order. You can include a decimal point (.), but no other special characters.
order.currency	Conditional	AN3[\s\S]3	Currency used for the order
order.preOrder	Optional	AN30[\s\S]30	Indicates whether cardholder is placing an order with a future availability or release date. This field can contain one of these values:MERCHANDISE_AVAILABLE: Merchandise available FUTURE_AVAILABILITY: Future availability
order.preOrderDate	AN8[\s\S]8	Optional	Expected date that a pre-ordered purchase will be available. Format: YYYYMMDD
order.reordered	Optional	true/false	Indicates whether the cardholder is reordering previously purchased merchandise. This field can contain one of these values: false: First time ordered true: Reordered
order.giftWrap	Optional	true/false	Boolean that indicates whether the customer requested gift wrapping for this purchase. This field can contain one of the following values: true: The customer requested gift wrapping. false: The customer did not request gift wrapping.
order.returnAccepted	Optional	true/false	Boolean that indicates whether returns are accepted for this order. This field can contain one of the following values: true: Returns are accepted for this order.- false: Returns are not accepted for this order.
order.totalOffersCount	Optional	AN3[\s\S]8	Total number of articles/items in the order as a numeric decimal count. Possible values: 00 - 99

Airline

The airline data structure holds passenger and trip leg airline information.

The airline passenger and leg items are counted up by changing the index-number [n], starting with 0.

Parameters

	Required	Format	Description
airline. actualFinalDesitination	Optional	AN10[\s\S]10	IATA Code for the actual final destination that the customer intends to travel to. It should be a destination on the completeRoute.
airline. completeRoute	Optional	AN255[\s\S]255	Concatenation of individual travel legs in the format ORIG1-DEST1[:ORIG2-DEST2...:ORIGn-DESTn], for example, SFO-JFK:JFK-LHR:LHR-CDG. For airport codes, see the IATA Airline and Airport Code Search. Note In your request, send either the complete route or the individual legs (_leg#_orig and _leg#_dest). If you send all the fields, the value of _complete_route takes precedence over that of the _leg# fields.
airline.depatureTime	Optional	[\s\S]30	Departure date and time of the first leg of the trip. Use one of the following formats: yyyy-MM-dd HH:mm z, yyyy-MM-dd hh:mm a z, yyyy-MM-dd hh:mma z, HH = hour in 24-hour format, hh = hour in 12-hour format, a = am or pm (case insensitive), z = time zone of the departing flight, for example: If the airline is based in city A, but the flight departs from city B, z is the time zone of city B at the time of departure. Important For travel information, use GMT instead of UTC, or use the local time zone. Examples: 2011-03-20 11:30 PM PDT, 2011-03-20 11:30pm GMT, 2011-03-20 11:30pm GMT-05:00 AN30
airline.journeyType	Optional	AN30[\s\S]30	Type of travel, for example one way or round trip.
airline.totalTaxAmount	Conditional	N10.N2[0-9]10.[0-9]2	The total amount of tax
airline.totalFeesAmount	Conditional	N10.N2[0-9]10.[0-9]2	The total fees
airline.totalFareAmount	Conditional	N10.N2[0-9]10.[0-9]2	The total fare
airline.ticketIssueDate	Conditional	AN10{19|20)([0-9]2)-(0[1-9]|1[0-2])-(0[1-9]|1[0-9]|2[0-9]|3[0-1]}	The date the booking/ticket was made
airline. ticketIssueAddress	Conditional	AN255[\s\S]255	The address that issued the ticket
airline. thirdPartyBooking	Conditional	AN255[\s\S]255	Indicates if the ticket was booked via a third party
airline. bookingType	Conditional	AN255[\s\S]255	The type of booking
airline. ticketDeliveryMethod	Conditional	AN255[\s\S]255	The delivery method of the ticket
airline. bookingRefNum	Conditional	AN255[\s\S]255	The booking reference number
airline.agentName	Conditional	AN255[\s\S]255	The agent name
airline.agentCode	Conditional	AN255[\s\S]255	The agent code
airline.passengers[n]. type	Conditional	AN3[\s\S]3	The passenger type ADT: Adult,CNN: Child, INF: Infant, YTH: Youth, STU: Student,SCR: Senior Citizen, MIL: Military
airline.passengers[n]. givenName	Conditional	AN48[\s\S]48	The given name of the passenger
airline.passengers[n]. surname	Conditional	AN48[\s\S]48	The given name of the passenger
airline.passengers[n]. nationality	Conditional	AN2	Passenger's nationality country(Country code).
airline.passengers[n]. ticketRestricted	Conditional	AN255[\s\S]255	Indicates if the passenger has a restricted ticket
airline.passengers[n]. ticketNumber	Conditional	AN255[\s\S]255	The passenger's ticket number
airline.passengers[n]. status	Conditional	AN25[\s\S]25	Your company's passenger classification, such as with a frequent flyer program. Standard, Gold，Platinum
airline.passengers[n]. phone	Conditional	AN255[\s\S]255	The passenger's phone
airline.passengers[n]. frequentFlyerNumber	Conditional	AN255[\s\S]255	The passenger's frequent flyer number
airline.passengers[n]. email	Conditional	AN255[\s\S]255	The passenger's email
airline.passengers[n]. dob	Conditional	AN255[\s\S]255	The passenger's date of birth
airline.passengers[n]. checkDigit	Conditional	AN255[\s\S]255	The check digit for the passenger
airline.passengers[n]. legs[n].ticketNumber	Conditional	AN255[\s\S]255	The ticket number for the leg
airline.passengers[n]. legs[n].taxAmount	Conditional	N10.N2[0-9]10.[0-9]2	The tax amount for the leg
airline.passengers[n]. legs[n].stopOverAllowed	Conditional	AN255[\s\S]255	Indicates if a stop over is allowed
airline.passengers[n]. legs[n].restrictions	Conditional	AN255[\s\S]255	Indicates if there is restrictions for the leg
airline.passengers[n]. legs[n].flightNumber	Conditional	AN255[\s\S]255	The flight number for the leg
airline.passengers[n]. legs[n].feesAmount	Conditional	N10.N2[0-9]10.[0-9]2	The fees for the leg
airline.passengers[n]. legs[n].fareBasis	Conditional	AN255[\s\S]255	The fare basis for the leg
airline.passengers[n]. legs[n].fareAmount	Conditional	N10.N2[0-9]10.[0-9]2	The fare amount for the leg
airline.passengers[n]. legs[n].exchangeTicketNum	Conditional	AN255[\s\S]255	The exchange ticket number for the leg
airline.passengers[n]. legs[n].departureTaxAmount	Conditional	N10.N2[0-9]10.[0-9]2	The departure tax amount for the leg
airline.passengers[n]. legs[n].departureCountry	Conditional	AN255[\s\S]255	The departure country for the passenger
airline.passengers[n]. legs[n].departureAirport	Conditional	AN255[\s\S]255	The departure airport for the passenger
airline.passengers[n]. legs[n].airlineName	Conditional	AN255[\s\S]255	The name of the airline for the leg
airline.passengers[n]. legs[n].airlineCode	Conditional	AN255[\s\S]255	The code of the airline for the leg
airline.passengers[n]. legs[n].departureTime	Conditional	AN255[\s\S]255	The departure time for the leg
airline.passengers[n]. legs[n].departureDate	Conditional	AN10{19|20)([0-9]2)-(0[1-9]|1[0-2])-(0[1-9]|1[0-9]|2[0-9]|3[0-1]}	The departure date for the leg
airline.passengers[n]. legs[n].arrivalCountry	Conditional	AN255[\s\S]255	The destination country for the leg
airline.passengers[n]. legs[n].arrivalAirport	Conditional	AN255[\s\S]255	The destination airport for the leg
airline.passengers[n]. legs[n].arrivalTime The	Conditional	AN255[\s\S]255	arrival time for the leg
airline.passengers[n]. legs[n].arrivalDate	Conditional	AN10{19|20)([0-9]2)-(0[1-9]|1[0-2])-(0[1-9]|1[0-9]|2[0-9]|3[0-1]}	The arrival date for the leg
airline.passengers[n]. legs[n].couponNumber	Conditional	AN255[\s\S]255	The coupon number for the leg
airline.passengers[n]. legs[n].classOfService	Conditional	AN255[\s\S]255	The class of service for the leg
airline.passengers[n]. legs[n].carrierCode	Conditional	AN255[\s\S]255	The carrier code for the leg
airline.passengers[n]. legs[n].timeToDeparture	Conditional	AN10[\s\S]10	The airline time to departure, in days, for the leg

Cart

The cart data structure holds product information about the shopping cart such as the product's ID, name, quantity and price.

The cart items are counted up by changing the index-number [n], starting with 0, and maximum 1000. Example: cart.items[0].name=First Cart Item

Parameters

	Required	Format	Description
cart.items[n]. name	Conditional	AN255[\s\S]255	The name of the item in the shopping cart. Example:cart.items[0].name=First Cart Item
cart.items[n]. merchantItemId	Conditional	AN255[\s\S]255	The unique identifier of the item in the shopping cart.
cart.items[n]. quantity	Conditional	N5[0-9]12(\.[0-9]3)	The number of items in the shopping cart.
cart.items[n]. type	Conditional	AN255[\s\S]255	The type of the purchased item in the shopping cart. Values can be: PHYSICAL, DIGITAL, MIXED, ANONYMOUS_DONATION, AUTHORITIES_PAYMENT, GIFT_CARD,HANDLING, SERVICE,SHIPPING,DEFAULT
cart.items[n]. sku	Optional	AN255[\s\S]255	The sku cart item.
cart.items[n]. currency	Conditional	currency code	The currency of the price of the shopping cart.
cart.items[n]. description	Conditional	AN2048[\s\S]2048	The description of the item in the shopping cart.
cart.items[n]. price	Conditional	N13[0-9]10.[0-9]2	The price of the item in the shopping cart. (including tax and discount). The item's price is independent
of the quantity.
cart.items[n]. totalAmount	Conditional	N13[0-9]10.[0-9]2	The total amount of the cart item including quantity.
cart.items[n]. taxAmount	Conditional	N13[0-9]10.[0-9]2	The tax amount of the cart item. The item's tax amount is independent of the quantity.
cart.items[n]. totalTaxAmount	Conditional	N13[0-9]10.[0-9]2	The total tax amount of the cart item.
cart.items[n]. tax	Conditional	AN6^(100(.00?)?)|([0-9]2(.[0-9]2)?)$	The tax percentage applied to the price of the item in the shopping cart.
cart.items[n]. shipping	Conditional	N10.N2[0-9]10.[0-9]2	The shipping amount applied to the item in the shopping cart.
cart.items[n]. discount	Conditional	N13[0-9]10.[0-9]2	The discount percentage applied to the price of the item in the shopping cart.
cart.items[n]. giftMessage	Optional	AN255[\s\S]255	Gift Message for the specific cart item
cart.items[n]. shippingMethod	Optional	AN255[\s\S]255	Shipping method for the cart item.
cart.items[n]. shippingInstructions	Optional	AN255[\s\S]255	Shipping instructions for the cart item.
cart.items[n]. shippingTrackingNumber	Optional	AN255[\s\S]255	Shipping tracking number for the cart item
cart.items[n]. originalPrice	Optional	AN255[\s\S]255	The cart item's price before discounts. The item's price is independent of the quantity.
cart.items[n]. quantityUnit	Optional	M, CM, KG, G, COUNT (default)	The cart item's unit of quanity.
cart.items[n]. productUrl	Optional	Valid URL	The cart item's URL.
cart.items[n]. imageUrl	Optional	Valid URL	The cart item's image URL.
cart.items[n]. totalDiscountAmount	Optional	N10.N2[0-9]10.[0-9]2	The cart item's total discount amount. The total discount amount is related to the discount percentage

Custom Parameters

Custom parameters are unspecified fields that can be used to send custom data. The data sent in these fields are echoed back in the response.

Parameters

	Required	Format	Description
customParameters[name]	Conditional	Name: AN64[a-zA-Z0-9._]64 Value: AN2048[\s\S]2048	A name value pair used for sending custom information. NOTE: customParameters that are sent from the client-side (e.g. for COPYandPAY) should be prepended with SHOPPER_*, for example customParameters[SHOPPER_customerId]

Risk Parameters

The following parameters are additional parameters available for risk checks e.g. using the ACI RedShield or Cybersource DM

Parameters

	Required	Format	Description
risk.parameters[name]	Optional	Name: AN32[a-zA-Z0-9._]32 Value: AN255[\s\S]255	A name value pair used for sending custom information related to the risk request.

Recurring Payment

You can perform recurring payments by just adding one additional parameter standingInstruction to the payment request. A recurring workflow consists of two phases:

• The initial payment request
• Subsequent payment requests

Sending the Initial Payment

During the initial payment, marked by the parameter standingInstruction.mode with the value INITIAL, standingInstruction.type with the value UNSCHEDULED and standingInstruction.source with the value CIT, the customer is present. Therefore this initial request should contain additional parameters that authenticate the customer like card.cvv for card payments, and also additional checks like 3D secure can be executed.

In checkout API you get this behavior out of the box, so all you have to add to the /checkouts request in step 1 this parameter:

Use Case 1 :

standingInstruction.mode=INITIAL  
standingInstruction.type=UNSCHEDULED  
standingInstruction.source=CIT

Use Case 2 :

standingInstruction.mode=INITIAL  
standingInstruction.type=RECURRING 
standingInstruction.source=CIT

Using the server-to-server integration, you either have the option to append the parameter standingInstruction to the initial /payments request that also stores the token like in this example:

curl https://ip:port/pay/v3/payments \
  -d "entityId=8a8294174b7ecb28014b9699220015ca" \
  -d "amount=2.00" \
  -d "currency=EUR" \
  -d "paymentBrand=VISA" \
  -d "paymentType=DB" \
  -d "card.number=4200000000000000" \
  -d "card.holder=Jane Jones" \
  -d "card.expiryMonth=05" \
  -d "card.expiryYear=2034" \
  -d "card.cvv=123" \
  -d "standingInstruction.mode=INITIAL" \
  -d "standingInstruction.type=UNSCHEDULED" \
  -d "standingInstruction.source=CIT" \
  -d "createRegistration=true" \
  -H "Authorization: Bearer OGE4Mjk0MTc0YjdlY2IyODAxNGI5Njk5MjIwMDE1Y2N8c3k2S0pzVDg="

For some cases you might want to use an alternative approach: If the shopper just registered his data without sending a payment at the same time you would have sent his payment directly to the /registrations endpoint as described here. In the same way as described above, the standingInstruction.mode=INITIAL, standingInstruction.type=UNSCHEDULED and standingInstruction.source=CIT parameters can be added to the request to indicate that this is the first in a series of recurring payments.

Sending a Repeated Payment

Any payment request following the initial one has to have the parameter standingInstruction.mode with the value REPEATED, standingInstruction.type with the value UNSCHEDULED , standingInstruction.source with the value MIT and standingInstruction.initialTransactionId with a value as ID received in the response of the initial CIT transaction. This flag not only indicates that the request is part of a series of payments on this account, but also tells the payment system that no user is present and therefore parameters like card.cvv or the 3D authentication shouldn't be present. This fact in combination with the stored payment data of the registration greatly reduces the number of parameters of such a request:

Use Case 1 :

standingInstruction.mode=REPEATED 
standingInstruction.type=UNSCHEDULED  
standingInstruction.source=MIT

Use Case 2 :

standingInstruction.mode=REPEATED 
standingInstruction.type=RECURRING  
standingInstruction.initialTransactionId=123456780 Note: This value is received in original CIT transaction response 
standingInstruction.source=MIT

Follow the section Card On File for possible standingInstruction parameters.

curl https://ip:port/pay/v3/registrations/{id}/payments \
 -d "entityId=8a8294174b7ecb28014b9699220015ca" \
 -d "amount=92.00" \
 -d "currency=EUR" \
 -d "paymentType=PA" \
 -d "standingInstruction.mode=REPEATED" \
 -d "standingInstruction.type=UNSCHEDULED" \
 -d "standingInstruction.source=MIT" \
 -H "Authorization: Bearer OGE4Mjk0MTc0YjdlY2IyODAxNGI5Njk5MjIwMDE1Y2N8c3k2S0pzVDg="

Tokenization

Tokenization (Scheme Token) allows you to store the payment data for later use. This can be useful for recurring payment scenarios.

EastPay provides two options for storing the payment data:

Store the data during a payment: When a shopper is checking out for the first time, he has to fill in his complete payment and address data. Use this option to automatically store his data during the payment for reuse in later transactions.

createRegistration=true

Store the data as stand-alone: If your site provides shoppers with an administrative area where they can register their payment details independent of a checkout-process, this option is for you.

Create Token

Used to digitize a card to create a server-based Token.

Request Parameters

	Required	Format	Description
card.holder	Optional	A128128	Holder of the credit card account
card.number	Required	N19[0-9]19	The PAN or account number of the card.
card.expiryMonth	Required	N2(0[1-9]|1[0-2])	The expiry month of the card.
card.expiryYear	Required	N4(19	20)([0-9]2)
card.cvv	Conditional	N4[0-9]4	The card security code or CVV
token.Brand	Conditional	AN32[a-zA-Z0-9_]32	The brand specifies the method of token for the request. This is optional if you want to use brand detection for credit cards, if not then it is mandatory.
token.Type	Required	A2	You can send payment requests with one of the following types: CT: create token DT: delete a token GT: get token information GA: get assets
merchant.id	Mandatory	N15[0-9]15	Acquirer-assigned Merchant identifier.

Sample:

curl http://host:port/pay/v3/tokenize\
  -d "entityId= tEntity1" \ 
  -d "entityType=PARTICIPATOR" \
  -d "merchant.Id=123456789012"\
  -d "paymentBrand=MASTER" \
  -d "paymentType=CT" \
  -d "card.number=5454545454545454" \
  -d "card.expiryMonth=06" \
  -d "card.expiryYear=2020" \
  -d "card.cvv=123" \
  -d "merchantTransactionId=202110103134154562355234" \
  -H "Authorization: Bearer OGE4Mjk0MTc0YjdlY2IyODAxNGI5Njk5MjIwMDE1Y2N8c3k2S0pzVDg="

Response Parameters

	Required	Format	Description
decision	Mandatory	A6464	The tokenization decision for this digitization request. APPROVED (Digitization request was approved) DECLINED (Digitization request was declined) REQUIRE_ADDITIONAL_AUTHENTICATION Digitization request was approved but optionally requires additional authentication.
token.UniqueReference	Mandatory	AN64	The unique reference allocated to the new Token. Serves as a unique identifier for all subsequent queries or management functions relating to this Token. Provided if the decision was APPROVED or REQUIRE_ADDITIONAL_AUTHENTICATION.

Below information is in addtionalData

	Required	Format	Description
brandLogoAssetId	Mandatory	AN64	The Mastercard or Maestro brand logo associated with this card. Use the Get Asset API to retrieve the actual asset. example: "dbc55444-986a-4896-b41c-5d5e2dd431e2"
issuerLogoAssetId	Mandatory	AN64	The logo of the issuing bank. example: "dbc55444-986a-4896-b41c-5d5e2dd431e2"
iconAssetId	Mandatory	AN64	The icon representing the primary brand(s) associated with this product.
cardBackgroundCombinedAssetId	Conditional	AN64	The card image used to represent the digital card in the wallet.
cardBackgroundAssetId	Conditional	AN64	The card image used to represent the digital card in the wallet. Conditional: either CardBackgroundCombined or CardBackground will be provided
foregroundColor	Mandatory	AN6	Foreground color, used to overlay text on top of the card image
issuerName	Mandatory	AN64	Name of the issuing bank.

Sample:

{
  "decision": "APPROVED",
  "tokenUniqueReference": "DWSPMC000000000132d72d4fcb2f4136a0532d3093ff1a45",
  "addtionalData" {
    "brandLogoAssetId": "800200c9-629d-11e3-949a-0739d27e5a66",
    "issuerLogoAssetId": "dbc55444-986a-4896-b41c-5d5e2dd431e2",
    "cardBackgroundAssetId": "456d27e5-629d-11e3-949a-0800200c9a66",
    "iconAssetId": "739d87e5-629d-11e3-949a-0800200c9a66",
    "foregroundColor": 0,
    "issuerName": "Issuing Bank",
    "shortDescription": "Bank Rewards MasterCard",
  },
}

Delete Token

Request Parameters

	Required	Format	Description
tokenUniqueReferences	Mandatory	AN64	The specific Token to be deleted.
causedBy	Mandatory	AN32	'CARDHOLDER' (operation requested by the Cardholder) or 'TOKEN_REQUESTOR'(operation requested by the merchant)
reasonCode	Mandatory	AN32	The reason for the action to be deleted. Must be one of 'SUSPECTED_FRAUD' (suspected fraudulent token transactions), 'OTHER' (Other - default used if value not provided).

curl http://host:port/pay/v3/tokenize\
  -d "entityId= tEntity1" \ 
  -d "entityType=PARTICIPATOR" \
  -d "merchant.Id=123456789012"\
  -d "paymentType=DT" \
  -d "tokenUniqueReferences": "DWSPMC000000000132d72d4fcb2f4136a0532d3093ff1a45",
  -d "causedBy": "CARDHOLDER",
  -d "reasonCode": "SUSPECTED_FRAUD"
  -d "merchantTransactionId=202110103134154562355234" \
-H "Authorization: Bearer OGE4Mjk0MTc0YjdlY2IyODAxNGI5Njk5MjIwMDE1Y2N8c3k2S0pzVDg="

Response Parameters

	Required	Format	Description
tokenUniqueReferences	Mandatory	AN64	The specific Token to be deleted.
status	Mandatory	AN32	The current status of Token. Must be either: INACTIVE (Token has not yet been activated) ACTIVE (Token is active and ready to transact) SUSPENDED (Token is suspended and unable to transact) DEACTIVATED (Token has been permanently deactivated).
suspendedBy	Mandatory	AN32	(CONDITIONAL only supplied if status is SUSPENDED) Who or what caused the Token to be suspended One or more values of: ISSUER - Suspended by the Issuer. TOKEN_REQUESTOR - Suspended by the Token Requestor MOBILE_PIN_LOCKED - Suspended due to the Mobile PIN being locked CARDHOLDER - Suspended by the Cardholder
statusTimestamp			The date and time the token status was last updated. YYYY-MM-DDThh:mm\:ss[.sss]Z YYYY-MM-DDThh:mm\:ss[.sss]±hh:mm Where [.sss] is optional and can be 1 to 3 digits.

Sample:

{
  "tokens": [
    {
      "tokenUniqueReference": "DWSPMC000000000132d72d4fcb2f4136a0532d3093ff1a45",
      "status": "SUSPENDED",
      "suspendedBy": [
        "CARDHOLDER"
      ]
    }
  ]
}

Get Token

Request Parameters

	Required	Format	Description
tokenUniqueReferences	Mandatory	AN64	The specific Information of the Token.

Response Parameters

	Required	Format	Description
tokenUniqueReferences	Mandatory	AN64	The specific Token to be deleted.
status	Mandatory	AN32	The current status of Token. Must be either: INACTIVE (Token has not yet been activated) ACTIVE (Token is active and ready to transact) SUSPENDED (Token is suspended and unable to transact) DEACTIVATED (Token has been permanently deactivated).
suspendedBy	Mandatory	AN32	(CONDITIONAL only supplied if status is SUSPENDED) Who or what caused the Token to be suspended One or more values of: ISSUER - Suspended by the Issuer. TOKEN_REQUESTOR - Suspended by the Token Requestor MOBILE_PIN_LOCKED - Suspended due to the Mobile PIN being locked CARDHOLDER - Suspended by the Cardholder
statusTimestamp			The date and time the token status was last updated. YYYY-MM-DDThh:mm\:ss[.sss]Z YYYY-MM-DDThh:mm\:ss[.sss]±hh:mm Where [.sss] is optional and can be 1 to 3 digits.

Below information in addtionalData

	Required	Format	Description
brandLogoAssetId	Mandatory	AN64	The MasterCard or Maestro brand logo associated with this card. Use the Get Asset API to retrieve the actual asset example: "dbc55444-986a-4896-b41c-5d5e2dd431e2"
issuerLogoAssetId	Mandatory	AN64	The logo of the issuing bank. example: "dbc55444-986a-4896-b41c-5d5e2dd431e2"
iconAssetId	Mandatory	AN64	The icon representing the primary brand(s) associated with this product.
cardBackgroundCombinedAssetId	Conditional	AN64	The card image used to represent the digital card in the wallet.
cardBackgroundAssetId	Conditional	AN64	The card image used to represent the digital card in the wallet. Conditional: either CardBackgroundCombined or CardBackground will be provided
foregroundColor	Mandatory	AN6	Foreground color, used to overlay text on top of the card image
issuerName	Mandatory	AN64	Name of the issuing bank.

Sample:

{
    "tokenUniqueReference": "DWSPMC000000000132d72d4fcb2f4136a0532d3093ff1a45",
    "status": "SUSPENDED",
    "suspendedBy": [
      "CARDHOLDER"
    ],
    "addtionalData": {
      "brandLogoAssetId": "800200c9-629d-11e3-949a-0739d27e5a66",
      "issuerLogoAssetId": "dbc55444-986a-4896-b41c-5d5e2dd431e2",
      "cardBackgroundCombinedAssetId": "739d27e5-629d-11e3-949a-0800200c9a66",
      "iconAssetId": "739d87e5-629d-11e3-949a-0800200c9a66",
      "foregroundColor": 0,
      "issuerName": "Issuing Bank"
    }
}

Get Card Art

Get card information and image

Request Parameters

	Required	Format	Description
assetId(Path)	Mandatory	AN64	An Asset ID corresponds to an individual Digital Asset. Digital Assets are returned as part of the addtionalData from the Tokenize Response.

curl http://host:port/pay/v3/asset/{assetId}\

Response Parameters

mediaContents array[mediaContent]

	Required	Format	Description
type	Mandatory	AN32	What type of media this is. Specified as a MIME type, which will be one of the following supported types: applicatoin/pdf (for images must be a vector PDF image) image/png (includes alpha channel) text/plain text/html
data	Mandatory	Base64-encoded data	The data for this item of media.
height	Mandatory	AN6	For image assets, the height of this image
width	Mandatory	AN6	For image assets, the width of this image

{
  "mediaContents": [
    {
      "type": "image/png",
      "data": "iVBORw0KGgoAAAANSUhEUgAAAXcAAAF3CAIAAADRopypAAAABGdBTUEAANbY1E9YMgAAAAlwSFlzAAAASAAAAEgARslrPgAAGtNJREFUeNrt3W9oW",
      "height": "375",
      "width": "375"
    }
  ]
}

Notifications

Please provide us a notification URL

Outbound API used by us to notify the Token Requestor of significant Token updates, such as when the Token is activated, suspended, unsuspended, or deleted; or when information about the Token or its product configuration has changed.

Request Parameters

We will put your entityID's "Authorization Bearer access-token" in the header and your system may verifiy it.

	Required	Format	Description
tokenUniqueReferences	Mandatory	AN64	The specific Token to be deleted.
status	Mandatory	AN32	The current status of Token. Must be either: INACTIVE (Token has not yet been activated),ACTIVE (Token is active and ready to transact), SUSPENDED (Token is suspended and unable to transact),DEACTIVATED (Token has been permanently deactivated).
suspendedBy	Mandatory	AN32	(CONDITIONAL only supplied if status is SUSPENDED) Who or what caused the Token to be suspended One or more values of: ISSUER - Suspended by the Issuer. TOKEN_REQUESTOR - Suspended by the Token Requestor,MOBILE_PIN_LOCKED - Suspended due to the Mobile PIN being locked, CARDHOLDER - Suspended by the Cardholder
statusTimestamp			The date and time the token status was last updated. YYYY-MM-DDThh:mm\:ss[.sss]Z,YYYY-MM-DDThh:mm\:ss[.sss]±hh:mm, Where [.sss] is optional and can be 1 to 3 digits.

Below information in addtionalData

	Required	Format	Description
brandLogoAssetId	Mandatory	AN64	The MasterCard or Maestro brand logo associated with this card. Use the Get Asset API to retrieve the actual asset. example: "dbc55444-986a-4896-b41c-5d5e2dd431e2"
issuerLogoAssetId	Mandatory	AN64	The logo of the issuing bank. example: "dbc55444-986a-4896-b41c-5d5e2dd431e2"
iconAssetId	Mandatory	AN64	The icon representing the primary brand(s) associated with this product.
cardBackgroundCombinedAssetId	Conditional	AN64	The card image used to represent the digital card in the wallet.
cardBackgroundAssetId	Conditional: either CardBackgroundCombined or CardBackground will be provided AN64 Conditional		The card image used to represent the digital card in the wallet.
foregroundColor	Mandatory	AN6	Foreground color, used to overlay text on top of the card image
issuerName	Mandatory	AN64	Name of the issuing bank.

{
  "tokenUniqueReference": "DWSPMC000000000132d72d4fcb2f4136a0532d3093ff1a45",
  "status": "SUSPENDED",
  "eventReasonCode": "SUSPECTED_FRAUD",
  "suspendedBy": [
            "CARDHOLDER"
   ],
  "addtionalData": {
    "brandLogoAssetId": "800200c9-629d-11e3-949a-0739d27e5a66",
    "issuerLogoAssetId": "dbc55444-986a-4896-b41c-5d5e2dd431e2",
    "cardBackgroundCombinedAssetId": "739d27e5-629d-11e3-949a-0800200c9a66",
    "cardBackgroundAssetId": "456d27e5-629d-11e3-949a-0800200c9a66",
    "iconAssetId": "739d87e5-629d-11e3-949a-0800200c9a66",
    "foregroundColor": 0,
    "issuerName": "Issuing Bank",
    "shortDescription": "Bank Rewards MasterCard",
  },
}

Response Parameters

You should acknowledge it with a 200 OK response.