Payment Processing Request - Step 1

{{url}}/ecom/execute_request/payments/v3/apple_pay/purchase

Input JSON Parameters

Parameter

Description

Data Format

Required

Example

The paymentData object to be encrypted with the payment key

applicationPrimaryAccountNumber

the account number of the card from which this transaction is funded

string

Yes

4,42E+15

applicationExpirationDate

Card validity period in YYMMDD format

string

Yes

261001

currencyCode

ISO 4217 numeric currency code

string

Yes

980

transactionAmount

Payment amount

string

Yes

2000

cardholderName

Name of the cardholder

string

Petro Ivanchenko

deviceManufacturerIdentifier

Hex-encoded device manufacturer identifier

string

Yes

paymentDataType

string

Yes

3DSecure

paymentData

onlinePaymentCryptogram

Payment cryptogram in Base64 format

string

Yes

AVn0rK8BiDxN2D/w2j8LMAABAAA=

eciIndicator

ECI indicator

string(1)

Additional data for payment

merchantRequestId

A unique identifier generated by the merchant's system, used to retrieve the operation status in case of an unknown error or disconnection.

string(36)

Yes

137d9304-0368-11ed-b939-0242ac120002

merchantId

Merchant ID generated in Ecom.

string(36)

Yes

137d9304-0368-11ed-b939-0242ac120002

desiredThreeDSMode

Indicates whether the merchant prefers to use 3DS in the purchase.

string(50)

Yes

Default: SHOULD MUST - Payment must be processed with 3DS. MUST_NOT - Payment must be processed without 3DS. SHOULD - If the card supports 3DS, verification is performed.

resultRedirectUrl

URL for redirecting the customer after 3DS authentication.

string(1000)

Google Help

notificationUrl

The URL to which the CallBack will be sent.

string(1000)

https://merchant.notification_url

notificationEncryption

Indicates whether CallBack data is encrypted.

string

true/false If not provided or set to false, CallBack data will be unencrypted.

date

Date and time of the payment.

string

Yes

{{currentdateT}}.00+00:00

comment

Additional transaction description provided by the merchant's customer.

string(1000)

///5555.25412

purpose

Payment purpose provided by the merchant.

string(255)

For goods

merchantComment

Additional information or comments from the merchant regarding the order.

string(255) a-zA-Z0-9 ,.;:@#$%'-=+1,256$

merchant Comment id 1258728c1

customerData

Object containing customer details.

object

Yes

senderCustomerId

Sender's customer ID.

string(255)

Yes

1258728c1

senderFirstName

Sender's first name.

string(30)

the value cannot contain only numbers
cannot contain periods or other special characters
cannot contain “NULL”, “3D SECURE”, “SURNAME”, “CARDHOLDER”, ”UNKNOWN”
only alphanumeric values are allowed
can accept a space and a hyphen, but can NOT consist exclusively of “ ” or “-“
a hyphen or space can be inside, but not at the beginning or end
For the apostrophe character, use the only available utf8 character - ' which in: utf 16 - u0027 utf32 - 00000027

Ivanenko

senderLastName

Sender's last name.

string(30)

the value cannot contain only numbers

cannot contain periods or other special characters

cannot contain “NULL”, “3D SECURE”, “SURNAME”, “CARDHOLDER”, ”UNKNOWN”

only alphanumeric values are allowed

can accept a space and a hyphen, but can NOT consist exclusively of “ ” or “-“

a hyphen or space can be inside, but not at the beginning or end

For the apostrophe character, use the only available utf8 character - ' which in: utf 16 - u0027 utf32 - 00000027

Ivan

senderMiddleName

Sender's middle name.

string(30)

the value cannot contain only numbers

cannot contain periods or other special characters

cannot contain “NULL”, “3D SECURE”, “SURNAME”, “CARDHOLDER”, ”UNKNOWN”

only alphanumeric values are allowed

can accept a space and a hyphen, but can NOT consist exclusively of “ ” or “-“

a hyphen or space can be inside, but not at the beginning or end

For the apostrophe character, use the only available utf8 character - ' which in: utf 16 - u0027 utf32 - 00000027

Ivanovich

senderEmail

Sender's email.

string(256)

mail@gmail.com

senderCountry

Sender's country code.

string(3) (ISO 3166, e.g., 804 for Ukraine)

804

senderRegion

Sender's region.

string(255)

Kyivska

senderCity

Sender's city.

string(25)

Kyiv

senderStreet

Sender's street.

string(35)

Sichovykh Striltsiv

senderAdditionalAddress

Additional sender address details (floor, house number, apartment).

string(255)

senderItn

Sender's tax identification number.

string(20)

1,2E+08

senderPassport

Sender's passport number.

string(255)

AN123456

senderIp

Sender's IP address.

string(50)

123.12.12.12

senderPhone

Sender's phone number.

string(20)

3,8E+11

senderBirthday

Sender's date of birth.

string(50)

31.12.2000

senderGender

Sender's gender.

string(50)

Male

senderZipCode

Sender's postal code.

string(50)

49000

Output Parameters:

Parameter

Description

Data Format

Example

type

Transaction type.

string

Purchase

rrn

RRN transaction number in MPS.

string

2554256963

purpose

Payment purpose.

string

For goods

comment

Comment.

string

test

coinAmount

Payment amount.

int

2000

merchantId

Merchant ID.

string

137d9304-0368-11ed-b939-0242ac120002

operationId

Transaction ID.

string

1712844596346b9F-WwrWZpq

ecomOperationId

Transaction ID in the Ecom system.

string

8c3303e9-7396-43b8-af4e-31d9facdde9b

merchantName

Merchant name.

string

KB test terminal

approvalCode

Authorization code.

string

39203

status

Transaction status.

string

Possible values: SUCCESS, FAIL, PENDING, REQUIRED_3DS, DESIRED_THREEDS_MODE_ERROR

transactionType

Transaction type in numerical form.

string

merchantRequestId

Merchant request id

string

72837906-f526-4aef-8d11-58d80b44cb75

transactionCurrency

Payment currency.

string

980

merchantCommission

Commission amount

string

createDateTime

Transaction creation date.

string

19.09.2024 15:29

modificationDateTime

Transaction modification date.

string

19.09.2024 15:29

actionCode

Response code

string

responseCode

Response details.

string

description

Response description.

string

approved

bankCode

Issuer bank name.

string

BANK_ALLIANCE

paymentSystem

Issuer MPS name.

string

MasterCard

productType

Terminal product type.

string

PURCHASE

notificationUrl

URL to which the CallBack is sent

string

https://merchant.notification_url/

paymentServiceType

Payment type

string

CARD/APPLE_PAY/GOOGLE_PAY

notificationEncryption

Callback data encryption feature

string

true/false If the parameter is not passed or false is passed, then the data in the CallBack will be unencrypted

cardNumberMask

Masked card number

string

5573********0304

desiredThreeDSMode

A feature that indicates whether the merchant wants to use the 3DS in the purchase or not.

string

MUST/SHOULD/MUST_NOT

threeDSMode

A parameter that indicates whether a 3DS is used in the purchase or not

string

MUST- pay with 3DS MUST_NOT- pay without 3DS

statusThreeDs

3DS holding status

string

Y - successful 3ds N - unsuccessful 3ds

threeDSServerTransId

Id of the transaction in the 3ds system

string

8a811df4-91e0-436b-a9ac-9b0772c96f28

acsTransId

Id of the transaction in the ACS system

string

3e17fabb-71e6-498e-8794-ef8c95c5ba6f

dsTransId

Transaction ID generated by Directory Server

string

12ebc556-82d3-4e35-9fb8-77ac18b050ea

eci

Electronic Commerce Indicator A code that indicates the security level of a transaction

string

processingMerchantId

Id of the merchant in PC

string

AE100000

processingTerminalId

Id of the terminal in the PS

string

AE100000

redirect3dsUrl

URL to redirect the client to the issuer's page for the 3DS pass

string

https://api-ecom-release.develop.bankalliance.ua/threeDS/getRedirectHtml/1702047427621BHu5X99yDbA

txnType

Under the type of transaction

enum

Possible values: NONCVV/noncvv- upon receipt of a given value of cvv input and its verification does not occur

senderCustomerId

Id of the sender's client

string

1258728c1

senderFirstName

Sender's first name

string

Ivanenko

senderLastName

Sender's last name

string

Ivan

senderMiddleName

Sender's middle name

string

Ivanovich

senderEmail

Sender's mail

string

mail@gmail.com

senderCountry

Sender's country

string

Ukraine

An example of a paymentData object

{
"applicationPrimaryAccountNumber":"{{applePayCardNumber}}",
"applicationExpirationDate":"{{applePayDate}}",
"currencyCode":"980",
"transactionAmount":"100",
"cardholderName":"{{cardholderName}}",
"deviceManufacturerIdentifier":"1255548888hfhhbbk",
"paymentDataType":"3DSecure",
"paymentData":{
"onlinePaymentCryptogram":"AVn0rK8BiDxN2D/w2j8LMAABAAA=",
"eciIndicator":"7"}
}

An example of a request body

{
    "paymentData":  "{{encryptedPaymentData}}",
    "merchantRequestId": "{{requestUUIDT}}",
    "desiredThreeDSMode": "MUST_NOT",
    "notificationUrl": "",
    "resultRedirectUrl": "",
    "purpose": "purpose",
    "comment": "comment",
    "merchantId": "137d9304-0368-11ed-b939-0242ac120002",
    "customerData": {
        "senderFirstName": "John",
        "senderLastName": "Doe",
        "senderMiddleName": "Fall",
        "senderEmail": "test@gmail.com",
        "senderCountry": "sender_country",
        "senderRegion": "sender_region",
        "senderCity": "sender_city",
        "senderStreet": "sender_street",
        "senderAdditionalAddress": "N 6",
        "senderItn": "12345",
        "senderPassport": "12345",
        "senderIp": "165.222.87.224",
        "senderPhone": "380967542344",
        "senderBirthday": "12/12/2000",
        "senderGender": "Male",
        "senderZipCode": "12345"
    },
    "date": "{{currentdateT}}.00+00:00"
}

Example response body without 3DS

{
    "type": "PURCHASE",
    "rrn": null,
    "purpose": "назначение",
    "comment": "тестовыйкомент",
    "coinAmount": null,
    "merchantId": "137d9304-0368-11ed-b939-0242ac120002",
    "operationId": null,
    "ecomOperationId": "459dc6d9-cbcb-4f80-9e96-7c09562f51d9",
    "merchantName": null,
    "approvalCode": null,
    "status": "PENDING",
    "transactionType": 35,
    "merchantRequestId": "afb51fa6-a2ec-4f02-b2d0-3a6efee611f0",
    "transactionCurrency": "980",
    "merchantCommission": null,
    "createDateTime": "2024.09.19 15:29:25.675",
    "modificationDateTime": "2024.09.19 15:29:25.675",
    "transactionResponseInfo": {
        "actionCode": null,
        "responseCode": null,
        "description": null
    },
    "bankCode": null,
    "paymentSystem": null,
    "productType": "PURCHASE",
    "notificationUrl": "https://api-ecom-prod.bankalliance.ua/mock",
    "paymentServiceType": "APPLE_PAY",
    "notificationEncryption": false,
    "cardNumberMask": null,
    "desiredThreeDSMode": "MUST_NOT",
    "threeDSMode": null,
    "statusThreeDs": null,
    "threeDSServerTransId": null,
    "redirect3dsUrl": null,
    "txnType": "null",
    "senderCustomerId": null,
    "senderFirstName": null,
    "senderLastName": null,
    "senderMiddleName": null,
    "senderEmail": null,
    "senderCountry": null,
    "senderRegion": null,
    "senderCity": null,
    "senderStreet": null,
    "senderAdditionalAddress": null,
    "senderItn": null,
    "senderPassport": null,
    "senderIp": null,
    "senderPhone": null,
    "senderBirthday": null,
    "senderGender": null,
    "senderZipCode": null,
    "senderBankCode": null,
    "senderPaymentSystem": null,
    "senderCardNumberMask": null
}

Example of response body from 3DS

{
    "type": "PURCHASE",
    "rrn": null,
    "purpose": "purpose",
    "comment": "comment",
    "coinAmount": null,
    "merchantId": "137d9304-0368-11ed-b939-0242ac120002",
    "operationId": "1712824711120IbbgGHLPNCm",
    "ecomOperationId": "895f15f5-26f7-43cd-8cc1-8f970148425b",
    "merchantName": null,
    "approvalCode": null,
    "status": "REQUIRED_3DS",
    "transactionType": 35,
    "merchantRequestId": "4bf82d10-472d-4ac5-b505-4b7d22ba2686",
    "transactionCurrency": "980",
    "merchantCommission": null,
    "createDateTime": "2024.09.19 15:29:25.675",
    "modificationDateTime": "2024.09.19 15:29:25.675",
    "transactionResponseInfo": {
        "actionCode": null,
        "responseCode": null,
        "description": null
    },
    "bankCode": null,
    "paymentSystem": null,
    "productType": "PURCHASE",
    "notificationUrl": "https://api-ecom-prod.bankalliance.ua/mock",
    "paymentServiceType": "APPLE_PAY",
    "notificationEncryption": false,
    "cardNumberMask": null,
    "desiredThreeDSMode": "MUST",
    "threeDSMode": "MUST",
    "statusThreeDs": null,
    "threeDSServerTransId": "0036703b-839f-4166-a1d8-5fe2f6fb2ea8",
    "redirect3dsUrl": null,
    "txnType": "null",
    "senderCustomerId": null,
    "senderFirstName": null,
    "senderLastName": null,
    "senderMiddleName": null,
    "senderEmail": null,
    "senderCountry": null,
    "senderRegion": null,
    "senderCity": null,
    "senderStreet": null,
    "senderAdditionalAddress": null,
    "senderItn": null,
    "senderPassport": null,
    "senderIp": null,
    "senderPhone": null,
    "senderBirthday": null,
    "senderGender": null,
    "senderZipCode": null,
    "senderBankCode": null,
    "senderPaymentSystem": null,
    "senderCardNumberMask": null
}

PreviousPURCHASE NextPayment Processing Request - Step 2 (3DS)

Last updated 2 months ago