NAV
shell

SmartPayments API

Authorization

For authentication every merchant has MerchantKey and Secret.

We use Basic auth: with every request you must send header:

Authorization: Basic base64(${merchantKey}:${secret})

Content-Type: application/json

API

API URLs

PCI DSS requests: https://chd-api.smartcore.pro

Other requests: https://api-gateway.smartcore.pro

Test cards

Before a production account is issued, you will have a test account, use the following cards to test integration.

Payment transaction

Card Result
4012000000003010 Frictionless Flow, Success
4003830171874018 Challenge Flow, Success or Fail
All Others Fail

Withdrawal transaction

Card Result
4012000000003010 Success
All Others Fail

Create payment form

Generate link to a payment form. PCI DSS compliance from your side is not required. Customer inputs card details into our payment form.

HTTP Request

POST https://api-gateway.smartcore.pro/initPayment

curl --location 'https://api-gateway.smartcore.pro/initPayment' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic dGVzdDpxd2VydHk=' \
--data-raw '{
    "account": "EUR-sandbox",
    "amount": 1000,
    "currency": "EUR",
    "order_id": "sandboxFormId_1015",
    "merchant_site": "https://merchant.site",
    "recurrent": false,
    "purpose": "description",
    "customer_first_name": "John",
    "customer_last_name": "Doe",
    "customer_address": "10 Downing Street",
    "customer_city": "London",
    "customer_zip_code": 121165,
    "customer_country": "GB",
    "customer_phone": "+442079460612",
    "customer_email": "[email protected]",
    "customer_ip_address": "127.0.0.1",
    "success_url": "https://site.com/success",
    "fail_url": "https://site.com/fail",
    "callback_url": "https://site.com/callback",
    "status_url": "https://site.com/redir"
}'

The above command returns JSON structured like this:

{
  "ACSUrl": null,
  "MD": null,
  "TermUrl": null,
  "description": "",
  "status": 1,
  "form_url": "https://payment.magua-pay.com/64a7e106d46c5db10d082b13",
  "order_id": "sandboxFormId_1015",
  "responseType": "REDIRECT"
}
Parameter Required Type Description
account true String Merchant Account Name
amount true Long Amount in Cents
currency true String Currency Alpha3 Code
order_id true String Merchant Order ID
merchant_site false String Merchant Site URL
recurrent false Boolean Is Recurrent Payment
purpose false String Order Description
customer_first_name true String Customer First Name
customer_last_name true String Customer Last Name
customer_address true String Customer Address
customer_city true String Customer city
customer_zip_code true String Customer Zip Code
customer_country true String Customer Country Code
customer_phone true String Customer Phone
customer_email true String Customer Email
customer_ip_address true String Customer IP Address
callback_url false String Callback URL which receives notifications when transaction status changes
success_url false String Redirect URL for successful transaction
fail_url false String Redirect URL for failed transaction
status_url false String Status URL

Create direct payment

Customer card details are transferred from merchant to our server. PCI DSS compliance from your side is required.

HTTP Request

POST https://chd-api.smartcore.pro/initPaymentHost2Host

curl --location 'https://chd-api.smartcore.pro/initPaymentHost2Host' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic dGVzdDpxd2VydHk=' \
--data-raw '{
    "payment_method": "card",
    "account": "EUR-sandbox",
    "amount": 1000,
    "currency": "EUR",
    "order_id": "sandboxId_1015",
    "merchant_site": "https://merchant.site",
    "recurrent": false,
    "purpose": "description",
    "customer_first_name": "John",
    "customer_last_name": "Doe",
    "customer_address": "10 Downing Street",
    "customer_city": "London",
    "customer_zip_code": 121165,
    "customer_country": "GB",
    "customer_phone": "+442079460612",
    "customer_email": "[email protected]",
    "customer_ip_address": "127.0.0.1",
    "success_url": "https://site.com/success",
    "fail_url": "https://site.com/fail",
    "callback_url": "https://site.com/callback",
    "status_url": "https://site.com/redir",
    "card_holder": "John Doe",
    "card_number": "4012000000003010",
    "card_exp_month": "02",
    "card_exp_year": "25",
    "card_cvv": "123",
    "apple_pay_dpan": "eyJhcHBsaWNhdGlvblByaW1hcnlBY2NvdW50TnVtYmVyIjoiKioqIiwiYXBwbGljYXRpb25FeHBpcmF0aW9uRGF0ZSI6IioqKiIsImN1cnJlbmN5Q29kZSI6Ijk3OCIsInRyYW5zYWN0aW9uQW1vdW50IjoxMDAsImRldmljZU1hbnVmYWN0dXJlcklkZW50aWZpZXIiOiIqKioiLCJwYXltZW50RGF0YVR5cGUiOiIzRFNlY3VyZSIsInBheW1lbnREYXRhIjp7Im9ubGluZVBheW1lbnRDcnlwdG9ncmFtIjoiKioqIiwiZWNpSW5kaWNhdG9yIjoiNyJ9fQ==",
    "apple_pay_payment_method_network": "Visa"
}'

The above command returns JSON structured like this:

{
  "form_url": "https://payment.magua-pay.com/64a7eec2d46c5db10d082b3d",
  "threeDSMethodData": null,
  "order_id": "64a7eec2d46c5db10d082b3d",
  "status": 1,
  "stage": null,
  "description": "",
  "endDate": null,
  "responseType": "REDIRECT",
  "err": null,
  "msg": null,
  "paReq": null,
  "creq": null,
  "md": null,
  "termUrl": null,
  "acsurl": null
}
Parameter Required Type Description
account true String Merchant Account Name
amount true Long Amount in Cents
currency true String Currency Alpha3 Code
order_id true String Merchant Order ID
merchant_site true String Merchant Site URL
recurrent false Boolean Is Recurrent Payment
purpose false String Order Description
customer_first_name true String Customer First Name
customer_last_name true String Customer Last Name
customer_address true String Customer Address
customer_city true String Customer City
customer_zip_code true String Customer Zip Code
customer_country true String Customer Country Code
customer_phone true String Customer Phone
customer_email true String Customer Email
customer_ip_address true String Customer IP Address
callback_url false String Callback URL which receives notifications when transaction status changes
success_url false String Redirect URL for successful transaction
fail_url false String Redirect URL for failed transaction
status_url false String Status URL
card_holder true String Customer Card holder
payment_method false String card or applePayDPan or googlePayDPan (card by default)
card_number true if card method String Customer Card number
card_exp_month true if card method String Customer Card expiration month
card_exp_year true if card method String Customer Card expiration year
card_cvv true if card method String Customer Card cvv
apple_pay_dpan true if applePayDPan method String Base64 of decoded value of paymentData.data token field
apple_pay_payment_method_network true if applePayDPan method String Value of paymentMethod.network token field
google_pay_dpan true if googlePayDPan method String Base64 of decoded value of paymentMethodData.tokenizationData.token paymentMethodData field
google_pay_payment_method_network true if googlePayDPan method String Value of paymentMethodData.info.cardNetwork paymentMethodData field
browser_accept_header false String Browser Accept Header
browser_user_agent false String Browser User Agent
browser_java_enabled false Boolean Is Java Enabled
browser_js_enabled false Boolean Is Javascript Enabled
browser_color_depth false String Browser Color Depth
browser_screen_height false String Browser Screen Height
browser_screen_width false String Browser Screen Width
browser_language false String Browser Language
browser_time_zone false String Browser Time Zone

Google Pay™

Overview

Google Pay™ offers a quick and simple payment method across websites, within apps, and at stores by utilizing the cards saved to your Google Account.

There are two methods to integrate Google Pay™ into your website. The first method is to use Hosted Checkout and the second method is to directly receive Google Pay™ token.

To create a payment using Hosted Checkout use initPayment request for the appropriate account.

To process a payment by directly receiving a Google Pay token involves two steps. First, you need to integrate with Google Pay™ API. Second, you need to integrate with PrimePay LLP. The process of the integration is described below.

Google Pay™ API Integration

The process of integration with Google Pay™ API is fully described here.

To integrate with Google Pay™, you need to implement PAYMENT_GATEWAY integration type.

Pass the following tokenizationSpecification to the PaymentDataRequest object:

const tokenizationSpecification = {
  type: 'PAYMENT_GATEWAY',
  parameters: {
    'gateway': 'primepay',
    'gatewayMerchantId': '<provided by PrimePay>'
  }
};

To get your integration approved by Google Pay™, ensure that you follow brand guidelines and fulfilled all the requirements.

PrimePay LLP API Integration

To integrate with PrimePay LLP, you need to use the API provided in this documentation.

To create direct payment use initPaymentHost2Host request, pass payment_method = 'googlePayDPan' and provide Base64 encoded value of the decrypted token.

Example of the initPaymentHost2Host request

curl --location 'https://chd-api.smartcore.pro/initPaymentHost2Host' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic dGVzdDpxd2VydHk=' \
--data-raw '{
    "payment_method": "googlePayDPan",
    "account": "EUR-sandbox",
    "amount": 1000,
    "currency": "EUR",
    "order_id": "sandboxId_1015",
    "merchant_site": "https://merchant.site",
    "recurrent": false,
    "purpose": "description",
    "customer_first_name": "John",
    "customer_last_name": "Doe",
    "customer_address": "10 Downing Street",
    "customer_city": "London",
    "customer_zip_code": 121165,
    "customer_country": "GB",
    "customer_phone": "+442079460612",
    "customer_email": "[email protected]",
    "customer_ip_address": "127.0.0.1",
    "success_url": "https://site.com/success",
    "fail_url": "https://site.com/fail",
    "callback_url": "https://site.com/callback",
    "status_url": "https://site.com/redir",
    "google_pay_dpan": "eyJzaWduYXR1cmUiOiIqKioiLCJpbnRlcm1lZGlhdGVTaWduaW5nS2V5Ijp7InNpZ25lZEtleSI6Insia2V5VmFsdWUiOiIqKioiLCJrZXlFeHBpcmF0aW9uIjoiMTcxMTQzNDQ1MjgzNiJ9Iiwic2lnbmF0dXJlcyI6WyIqKioiXX0sInByb3RvY29sVmVyc2lvbiI6IkVDdjIiLCJzaWduZWRNZXNzYWdlIjoieyJlbmNyeXB0ZWRNZXNzYWdlIjoiKioqIiwiZXBoZW1lcmFsUHVibGljS2V5IjoiKioqIiwidGFnIjoiKioqIn0ifQ",
    "google_pay_payment_method_network": "Visa"
}'

Check transaction status

HTTP Request

POST https://api-gateway.smartcore.pro/check

curl --location 'https://api-gateway.smartcore.pro/check' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic dGVzdDpxd2VydHk=' \
--data '{
    "order_id": "sandboxId_1015"
}'

The above command returns JSON structured like this:

{
  "order_id": "sandboxFormId_1015",
  "status": 2,
  "amount": 1000,
  "card": {
    "number": "401200******3010",
    "bin": "401200",
    "country": "Spain",
    "iso": "ESP",
    "type": "VISA"
  },
  "errorMessage": null,
  "cascadeErrors": null,
  "endDate": "2023-07-04T13:22:07.087Z",
  "authorize_status": null,
  "type": "Payment",
  "firstName": "John",
  "lastName": "Doe"
}

In case of an error the response will be:

{
  "order_id": "sandboxFormId_1016",
  "status": -1,
  "amount": 1000,
  "card": {
    "number": "401200******3010",
    "bin": "401200",
    "country": "Spain",
    "iso": "ESP",
    "type": "VISA"
  },
  "errorMessage": "PLATFORM_ERROR_GATE_NOT_FOUND",
  "cascadeErrors": [
    {
      "gatePriority": 0,
      "errorCategory": "PLATFORM_ERROR_ANTIFRAUD_RULES"
    },
    {
      "gatePriority": 1,
      "errorCategory": "PLATFORM_ERROR_GATE_SKIPPED"
    },
    {
      "gatePriority": 2,
      "errorCategory": "PLATFORM_ERROR_CARD_BRAND_UNAVAILABLE"
    }
  ],
  "endDate": "2024-01-12T11:18:26.678Z",
  "authorize_status": null,
  "type": "Payment",
  "firstName": "John",
  "lastName": "Doe"
}
Parameter Required Type Description
order_id true String Merchant Order ID

Transaction statuses

Status Description
1 Processing
2 Success
-1 Fail

Refund

Refund existing transaction.

HTTP Request

POST https://api-gateway.smartcore.pro/refund

curl --location 'https://api-gateway.smartcore.pro/refund' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic dGVzdDpxd2VydHk=' \
--data '{
    "order_id": "sandboxId_1015",
    "amount": 1000,
    "reason": "refund"
}'

The above command returns JSON structured like this:

{
  "success": false,
  "message": "",
  "refund_id": "0719e590-1cda-11ee-82d1-a58ec416e4a2",
  "parentTransaction": "64a40ee3c4125fdb1d5cf635"
}
Parameter Required Type Description
order_id true String Merchant Order ID
amount true Long Amount in Cents
reason true String Refund Reason
callback_url false String Callback URL which receives notifications when transaction status changes

Recurrent

Create recurrent payment from existing transaction.

HTTP Request

POST https://api-gateway.smartcore.pro/recurrent

curl --location 'https://api-gateway.smartcore.pro/recurrent' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic dGVzdDpxd2VydHk=' \
--data '{
    "order_id": "sandboxRecurId_1015",
    "parent_order_id": "sandboxId_1015",
    "amount": 1000,
    "reason": "test recurrent"
}'

The above command returns JSON structured like this:

{
  "success": true,
  "message": "",
  "payment_id": "0719e590-1cda-11ee-82d1-a58ec416e4a2",
  "err": null
}
Parameter Required Type Description
order_id true String Merchant Order ID
parent_order_id true String Merchant Order ID of Parent Transaction
amount true Long Amount in Cents
reason true String Order Description
callback_url false String Callback URL which receives notifications when transaction status changes

Create withdrawal transaction

Create money withdrawal to card, phone number or account.

HTTP Request

POST https://chd-api.smartcore.pro/withdrawal/init

curl --location 'https://chd-api.smartcore.pro/withdrawal/init' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic dGVzdDpxd2VydHk=' \
--data '{
    "account": "EUR-sandbox-payout",
    "order_id": "testPayout_1050",
    "amount": 10000,
    "customer_card_number": "4123540003981114",
    "merchant_site": "https://merchant.site",
    "customer_first_name": "John",
    "customer_middle_name": "Jerom",
    "customer_last_name": "Doe",
    "customer_phone": "+442079460612",
    "customer_birthdate": "06.06.1997",
    "customer_zip_code": "121165",
    "callback_url": "https://site.com/callback"
}'

The above command returns JSON structured like this:

{
  "order_id": "testPayout_1050",
  "status": 1,
  "card": {
    "number": "401200******3010",
    "bin": "401200",
    "country": "Spain",
    "iso": "ESP",
    "type": "VISA"
  },
  "err": null,
  "msg": null
}
Parameter Required Type Description
account true String Merchant Account Name
amount true Long Amount in Cents
order_id true String Merchant Order ID
purpose false String Order description
merchant_site false String Merchant Site URL
customer_card_number false String Customer Card Number
customer_card_exp_month false String Customer Card Expiration Month
customer_card_exp_year false String Customer Card Expiration Year
customer_first_name false String Customer First Name
customer_last_name false String Customer Last Name
customer_middle_name false String Customer Middle Name
customer_phone false String Customer Phone
customer_birthdate false String Customer Birthdate
customer_zip_code false String Customer Zip Code
callback_url false String Callback URL which receives notifications when transaction status changes
account_withdrawal false String Withdrawal Account name
account_withdrawal_holder false String Withdrawal Account holder
account_withdrawal_iin false String Withdrawal Account IIN
payment_method false String Withdrawal Phone
provider_id false String Withdrawal Provider ID
customer_ip_address false String Customer IP Address (required for Crederes driver)
account_withdrawal_bin false String Withdrawal Account BIN
account_withdrawal_kbe false String Withdrawal Account KBE
account_withdrawal_bank_code false String Withdrawal Account Bank Code
account_withdrawal_bank_name false String Withdrawal Account Bank Name
account_withdrawal_cnp false String Withdrawal Purpose of Payment Code
account_withdrawal_recipient_code false String Withdrawal Recipient Code
account_withdrawal_sender_code false String Withdrawal Sender Code
account_withdrawal_recipient_rnn false String Withdrawal Recipient RNN
account_withdrawal_recipient_name false String Withdrawal Recipient Name

Get withdrawal balance

Get available withdrawal balance.

HTTP Request

POST https://api-gateway.smartcore.pro/withdrawal/balance/get

curl --location 'https://api-gateway.smartcore.pro/withdrawal/balance/get' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic dGVzdDpxd2VydHk=' \
--data '{
    "account": "EUR-sandbox-payout"
}'

The above command returns JSON structured like this:

{
  "balance": 10000,
  "holdBalance": 0,
  "rollingBalance": 0
}
Parameter Required Type Description
account true String Merchant Account Name

Create authorize-capture payment

Create two-step payment with authorization and capture.

HTTP Request

POST https://chd-api.smartcore.pro/authorize

curl --location 'https://chd-api.smartcore.pro/authorize' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic dGVzdDpxd2VydHk=' \
--data-raw '{
    "account": "EUR-sandbox",
    "amount": 1000,
    "currency": "EUR",
    "order_id": "sandboxId_1016",
    "merchant_site": "https://merchant.site",
    "recurrent": false,
    "purpose": "description",
    "customer_first_name": "John",
    "customer_last_name": "Doe",
    "customer_address": "10 Downing Street",
    "customer_city": "London",
    "customer_zip_code": 121165,
    "customer_country": "GB",
    "customer_phone": "+442079460612",
    "customer_email": "[email protected]",
    "customer_ip_address": "127.0.0.1",
    "success_url": "https://site.com/success",
    "fail_url": "https://site.com/fail",
    "callback_url": "https://site.com/callback",
    "status_url": "https://site.com/redir",
    "card_holder": "John Doe",
    "card_number": "4012000000003010",
    "card_exp_month": "02",
    "card_exp_year": "25",
    "card_cvv": "123"
}'

The above command returns JSON structured like this:

{
  "form_url": "https://payment.magua-pay.com/64a7eec2d46c5db10d082b3d",
  "threeDSMethodData": null,
  "order_id": "64a7eec2d46c5db10d082b3d",
  "status": 1,
  "stage": null,
  "description": "",
  "endDate": null,
  "responseType": "REDIRECT",
  "err": null,
  "msg": null,
  "paReq": null,
  "creq": null,
  "md": null,
  "termUrl": null,
  "acsurl": null
}
Parameter Required Type Description
account true String Merchant Account Name
amount true Long Amount in Cents
currency true String Currency Alpha3 Code
order_id true String Merchant Order ID
merchant_site true String Merchant Site URL
recurrent false Boolean Is Recurrent Payment
purpose false String Order Description
customer_first_name true String Customer First Name
customer_last_name true String Customer Last Name
customer_address true String Customer Address
customer_city true String Customer City
customer_zip_code true String Customer Zip Code
customer_country true String Customer Country Code
customer_phone true String Customer Phone
customer_email true String Customer Email
customer_ip_address true String Customer IP Address
success_url false String Redirect URL for Successful Transaction
fail_url false String Redirect URL for Failed Transaction
callback_url false String Callback URL which receives notifications when transaction status changes
status_url false String Status URL
card_holder true String Customer Card Holder
card_number true String Customer Card Number
card_exp_month true String Customer Card Expiration Month
card_exp_year true String Customer Card Expiration Year
card_cvv true String Customer Card CVV

Capture authorize-capture payment

Capture authorized payment.

HTTP Request

POST https://api-gateway.smartcore.pro/capture

curl --location 'https://api-gateway.smartcore.pro/capture' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic dGVzdDpxd2VydHk=' \
--data '{
    "order_id": "sandboxId_1016"
}'

The above command returns JSON structured like this:

{
  "order_id": "sandboxId_1016",
  "status": 2,
  "amount": 1000,
  "card": {
    "number": "401200******3010",
    "bin": "401200",
    "country": "Spain",
    "iso": "ESP",
    "type": "VISA"
  },
  "errorMessage": null,
  "cascadeErrors": null,
  "endDate": "2023-07-04T13:22:07.087Z",
  "authorize_status": null,
  "type": "Payment",
  "firstName": "John",
  "lastName": "Doe"
}
Parameter Required Type Description
order_id true String Merchant Order ID

Cancel authorize-capture payment

Cancel authorized payment.

HTTP Request

POST https://api-gateway.smartcore.pro/cancel

curl --location 'https://api-gateway.smartcore.pro/cancel' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic dGVzdDpxd2VydHk=' \
--data '{
    "order_id": "sandboxId_1016"
}'

The above command returns JSON structured like this:

{
  "order_id": "sandboxId_1016",
  "status": -1,
  "amount": 1000,
  "card": {
    "number": "401200******3010",
    "bin": "401200",
    "country": "Spain",
    "iso": "ESP",
    "type": "VISA"
  },
  "errorMessage": null,
  "cascadeErrors": null,
  "endDate": "2023-07-04T13:22:07.087Z",
  "authorize_status": null,
  "type": "Payment",
  "firstName": "John",
  "lastName": "Doe"
}
Parameter Required Type Description
order_id true String Merchant Order ID

Get transaction list

Steps:

  1. You should create download task
  2. Check task status, and wait for status 2
  3. Download result

Authorization

This method accepts only basic authorization

Create download task

POST https://service.magua-pay.com/aggregation-service/public/transaction/excel

Create download task 

curl --location 'https://service.magua-pay.com/aggregation-service/public/transaction/excel' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic dGVzdDpxd2VydHk=' \
--data-raw '{
    "type": "Payment",
    "status": 2,
    "dateFrom": 1674507600000,
    "dateTo": 1679678900200
}'

The above command returns JSON structured like this:

{
  "id": "641def1d70836759e8af7dd4",
  "status": 1
}

Request parameters

Parameter Required Type Description
type true String Transaction type: Payment, Withdrawal, Refund
status true Long 2 - success, 1 - pending, -1 - fail
dateFrom true Long date from unix timestamp milliseconds
dateTo true String date until unix timestamp milliseconds

Response parameters

Parameter Required Type Description
id true String task id
status true Long 2 - success, 1 - pending, -1 - fail

Get task status

GET https://service.magua-pay.com/aggregation-service/public/transaction/excel/task/{taskId}

Get task status

curl --location 'https://service.magua-pay.com/aggregation-service/public/transaction/excel/task/641def1d70836759e8af7dd4' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic dGVzdDpxd2VydHk='

The above command returns JSON structured like this:

{
  "id": "641def1d70836759e8af7dd4",
  "status": 2
}

Request parameters

Parameter Required Type Description
taskId true String task id from creation request

Response parameters

Parameter Required Type Description
id true String task id
status true Long 2 - success, 1 - pending, -1 - fail

Get task result

GET https://service.magua-pay.com/aggregation-service/public/transaction/excel/task/{taskId}/result

Get task status

curl --location 'https://service.magua-pay.com/aggregation-service/public/transaction/excel/task/641def1d70836759e8af7dd4/result' \
--header 'Authorization: Basic dGVzdDpxd2VydHk='

The above command returns xlsx document.

Request parameters

Parameter Required Type Description
taskId true String task id from creation request
shell