Integration
To use the Masterpass service, you need:
-
Become a partner of the Masterpass program. Sign up either directly or with assistance of your account manager.
-
Ask your account manager to configure Masterpass parameters for your shop.
-
Implement additional integration methods:
-
Add the Masterpass logo on all pages. Ask your account manager for logo placement requirements.
Open a user session in Masterpass
The method is used to authorize a user in Masterpass in the following cases:
- First and subsequent logins to the application;
- The user session expired. Masterpass returns the error with
Error_Code = 8
orError_Code = 16
. It is necessary to make a renewed request to open a user session and get a list of cards.
Request
Send a POST
request to https://demo-gateway.begateway.com/masterpass/login
with the following parameters:
Parameter | Type | Description |
---|---|---|
phone * required |
string | The customer's phone number. |
fingerprint * required |
string | A Base64-encoded set of unique parameters for the customer device. The guide for creating a parameter value is published in the Masterpass account (ask your account manager). |
phone_check_date | string | A field for the last successful date of phone verification on the merchant side in the Date(1612341218000) (epoch time in milliseconds) format. |
channel | integer | 0 = Recurring 1 = WEB2 = APP iOS3 = APP Android4 = TVE5 = SmartTV6 = Smart devices7 = USSD8 = IVR9 = Offline10 = Other. |
test | boolean | If the operation is a test one, set to true . Otherwise, false . |
Example of the request
{
"fingerprint": "SGVpZ2h0PTg5NjtXaWR0aD00MTQ7T1NWZXJzaW9uPVZlcnNpb24gMTIuMS40IChCdWlsZCAxNkQ1Nyk7RGV2aWNlSWQ9Njk5NkI3QTYtMjREOS00Rj\nVBLUJFMDktOTlBRDQyMEFBRkZGO1RpbWVab25lPUV1cm9wZS9Nb3Njb3c7TW9kZWw9aVBob25lIFhSO09TPWlPUztQaG9uZUlkPTRDNDQzQzI2LUNE\nQTItNDYxQS05QUVGLTNEQkNFMTJCMkVFNztWZXJzaW9uUmVsZWFzZT0xMi4xLjQ7IFJlbW90ZUlwPTkxLjIzOC4xMjAuMTcxO1Bhc3N3b3JkPWNhMz\ndiMzEzMmFhNTE2YzQ1MzdiYWYyOGJiYzI1OTk5OWU0ZDA5ZTZlZTE1NWFkYjNkOGRiMDMzODJlYWI5ODk7WEZvcndhcmRlZEZvcj05MS4yMzguMTIw\nLjE3MSwyMTYuMTE5LjIwOS42NDtPVFA9MDNBQzY3NDIxNkYzRTE1Qzc2MUVFMUE1RTI1NUYwNjc5NTM2MjNDOEIzODhCNDQ1OUUxM0Y5NzhEN0M4ND\nZGNDtBQT1VMA==",
"phone": "77707811122",
"phone_check_date": "Date(1612341218000)",
"channel": 2,
"test": true
}
Response
When the request is processed, the system sends a response specifying the following parameters:
Parameter | Type | Description |
---|---|---|
status | string | A response status. Returned in case of an error. |
error_code | integer | An error code. Returned in case of an error. |
error | string | An error message. Returned in case of an error. |
is_otp_required | boolean | If true , OTP check is required. Otherwise, false . |
session | string | A user session ID. |
user_status | integer | A user status in Masterpass. If the status is not 1 , a request to get a card list is not required. |
Example of the successful response
{
"session": "c96fe83d-366c-420c-9038-da0fae844f0c",
"is_otp_required": false,
"user_status": 1
}
Error codes
If errors occur, use the following error_code
description to detect the reason.
Error code | Description | Comment |
---|---|---|
0 | None | Successful completion. |
1 | The service is not available for this card/user | The current user is blacklisted. |
2 | Api not allowed | Method call is prohibited after exceeding the allowed number of requests. |
8 | No user was found by the passed session | А non-existing session was transferred, or the session has expired. Session should be re-opened. |
10 | Wrong phone format | Invalid phone number format. |
11 | Empty DeviceId | The required parameter DeviceId is not transferred to Fingerprint , the field is empty or contains spaces. |
13 | Internal error while encrypting the response | Internal system error, additional check with Masterpass command required. |
15 | Merchant with such a name and password not found | The mandatory Merchant field was not transferred in the request or the Merchant with that name was not found. |
19 | The service is not available for this card/user or wrong params | The user is blacklisted. The maximum number of attempts to send OTP has been exceeded. The limitation is considered simultaneously for all Merchants. The request was sent with an incorrect or incomplete set of parameters. |
20 | Internal error | Internal system error, additional check with Masterpass command required. |
23 | RequestTokenNotFound | The transferred RequestToken value does not exist. |
35 | Wrong params | Mandatory parameters are not transferred to Fingerprint . |
44 | API_NOT_ALLOWED | Certificate not found or certificate expired or signing error. |
Add a new card to Masterpass
Before you start
Open a user session before you save a new card in Masterpass.
Request
To save a new card, use payment or authorization requests with the following parameters:
Parameter | Type | Description |
---|---|---|
additional_data | object | Section of additional payment details. |
contract * обязательный |
array | Array with the following parameter:recurring - Demo PSP returns a card token to use it in subsequent charges without to enter a card data again. Customer agrees to be charged regularly, but initially the customer must make a payment with full card data including CVC/CVV code and pass 3-D Secure verification. |
masterpass | object | Section of the Masterpass service parameters. |
params | object | Section of the Masterpass parameters. |
session * required |
string | User session ID. |
Example of the request for the payment transaction
{
"request": {
"amount": 100,
"currency": "USD",
"description": "www",
"tracking_id": "save_card_test_masterpass_success_2",
"billing_address": {
"first_name": "John",
"last_name": "Doe",
"country": "US",
"city": "Denver",
"state": "CO",
"zip": "96002",
"address": "1st Street"
},
"credit_card": {
"number": "4200000000000000",
"verification_value": "123",
"holder": "John Doe",
"exp_month": "05",
"exp_year": "2026"
},
"additional_data": {
"contract": [
"recurring"
],
"masterpass": {
"params": {
"session": "a6fd8624-8060-46b3-b343-7a93126fd57f"
}
}
},
"customer": {
"ip": "127.0.0.1",
"email": "email@example.com",
"birth_date": "1998-01-31"
},
"test": true
}
}
Response
If the shop participates in the Masterpass program, after the payment is processed, Demo PSP makes a request to save the card in Masterpass. The repose contains the Masterpass token and the result of saving the card in Masterpass.
Info
If a payment is made only to save a card, after you receive a result of saving the card, make a refund.
Example of the response for the payment transaction in case of successful card saving
{
"transaction": {
"uid": "10134-ca74085dff",
"status": "successful",
"amount": 100,
"currency": "USD",
"description": "www",
"type": "payment",
"payment_method_type": "credit_card",
"tracking_id": null,
"message": "Successfully processed",
"test": true,
"created_at": "2021-03-15T07:47:27.904Z",
"updated_at": "2021-03-15T07:47:31.095Z",
"paid_at": "2021-03-15T07:47:31.055Z",
"expired_at": null,
"closed_at": null,
"settled_at": null,
"manually_corrected_at": null,
"language": "en",
"redirect_url": "https://demo-gateway.begateway.com/process/10134-ca74085dff",
"credit_card": {
"holder": "John Doe",
"stamp": "b3839d334ba40e89168d60cd9f9d1390aee3fe67dd4d5c41adbf3998043eaef8",
"brand": "visa",
"last_4": "0000",
"first_1": "4",
"bin": "420000",
"issuer_country": null,
"issuer_name": null,
"product": null,
"exp_month": 5,
"exp_year": 2026,
"token_provider": null,
"token": "495f97d6-862a-4445-b537-06d4b3fa392f"
},
"receipt_url": "https://demo-backoffice.begateway.com/customer/transactions/10134-ca74085dff/f3dcf8284bbe70f87d1714095eb8101053ec4de77dd04e5c74aa280e54276b3d",
"id": "10134-ca74085dff",
"additional_data": {
"contract": [
"recurring"
],
"masterpass": {
"params": {
"session": "35b55f8e-36d4-467a-b41f-28468a031898"
},
"result": {
"status": "successful",
"message": "Postback successfully finished.",
"token": "31b1e418-6a56-490d-bb5b-15f11a2040d8"
}
}
},
"payment": {
"auth_code": "654321",
"bank_code": "05",
"rrn": "999",
"ref_id": "777888",
"message": "Payment was approved",
"amount": 100,
"currency": "USD",
"billing_descriptor": "test descriptor",
"gateway_id": 288,
"status": "successful"
},
"avs_cvc_verification": {
"avs_verification": {
"result_code": "1"
},
"cvc_verification": {
"result_code": "1"
}
},
"customer": {
"ip": "127.0.0.1",
"email": "email@example.com",
"device_id": null,
"birth_date": "1998-01-31"
},
"billing_address": {
"first_name": "John",
"last_name": "Doe",
"address": "1st Street",
"country": "US",
"city": "Denver",
"zip": "96002",
"state": "CO",
"phone": null
}
}
}
Error codes
If errors occur, use the following error_code
description to detect the reason.
Error code | Description | Comment |
---|---|---|
0 | Successful completion | |
1 | The service is not available for this card/user | The current card is blacklisted. It is recommended to update the list of cards by calling the GetCards method or let the user save a new card |
2 | Card is not activated | Card details in this status cannot be received via GetCard method. It is recommended to update the list of cards by calling the GetCards method or let the user save a new card |
3 | The card was not found by the token | It is recommended to update the list of cards by calling the GetCards method or let the user save a new card |
5 | Customer with this phone number not found | - |
12 | This transaction is marked as fraud | - |
15 | Merchant with such a name and password not found | The required Merchant field was not transferred in the request, or the Merchant with the same name was not found |
16 | Session for the card not found, and it is not recurrent | A non-existing session was transferred, or the session has expired |
17 | Amount <= 0 | The value of the Amount parameter should be strictly greater than 0 |
19 | Wrong params | The required parameter Amount is not transferred in the request, empty field or contains something other than numbers. |
44 | API_NOT_ALLOWED | Certificate not found or certificate expired or signing error |
Example of the response with an error occurred while a card is being saved in Masterpass
{
"transaction": {
"uid": "9706-fde9808c80",
"status": "successful",
"amount": 100,
"currency": "USD",
"description": "www",
"type": "payment",
"payment_method_type": "credit_card",
"tracking_id": "save_card_test_masterpass_success_2",
"message": "Successfully processed",
"test": true,
"created_at": "2021-02-12T12:13:43.314Z",
"updated_at": "2021-02-12T12:13:49.492Z",
"paid_at": "2021-02-12T12:13:49.439Z",
"expired_at": null,
"closed_at": null,
"settled_at": null,
"manually_corrected_at": null,
"language": "en",
"redirect_url": "https://demo-gateway.begateway.com/process/9706-fde9808c80",
"credit_card": {
"holder": "John Doe",
"stamp": "b3839d334ba40e89168d60cd9f9d1390aee3fe67dd4d5c41adbf3998043eaef8",
"brand": "visa",
"last_4": "0000",
"first_1": "4",
"bin": "420000",
"issuer_country": null,
"issuer_name": null,
"product": null,
"exp_month": 5,
"exp_year": 2026,
"token_provider": null,
"token": "330e7e46-2958-41f1-8272-42ea3e05ec4a"
},
"receipt_url": "https://demo-backoffice.begateway.com/customer/transactions/9706-fde9808c80/c13d59bea3867441f360af4d4a7a75d6398d7d2eed34dd48185ee2e6df0522b4",
"id": "9706-fde9808c80",
"additional_data": {
"contract": [
"recurring"
],
"masterpass": {
"params": {
"session": "session"
},
"result": {
"status": "failed",
"message": "SaveCard failed.",
"error": "Masterpass error response",
"error_message": null,
"error_code": 8
}
}
},
"payment": {
"auth_code": "654321",
"bank_code": "05",
"rrn": "999",
"ref_id": "777888",
"message": "Payment was approved",
"amount": 100,
"currency": "USD",
"billing_descriptor": "test descriptor",
"gateway_id": 288,
"status": "successful"
},
"avs_cvc_verification": {
"avs_verification": {
"result_code": "1"
},
"cvc_verification": {
"result_code": "1"
}
},
"customer": {
"ip": "127.0.0.1",
"email": "email@example.com",
"device_id": null,
"birth_date": "1998-01-31"
},
"billing_address": {
"first_name": "John",
"last_name": "Doe",
"address": "1st Street",
"country": "US",
"city": "Denver",
"zip": "96002",
"state": "CO",
"phone": null
}
}
}
Get cards from Masterpass
Before you start
Open a user session before getting a list of cards from Masterpass.
Info
Demo PSP removes from the list of cards brands that Demo PSP will not be able to process (the shop's gateway may not support the user's card brand, that he previously linked to Masterpass).
Request
Send a POST
request to https://demo-gateway.begateway.com/masterpass/get_cards
with the following parameters:
Parameter | Type | Description |
---|---|---|
session * required |
string | A user session ID. |
test | boolean | If the operation will be a test one, set to true . Otherwise, false . |
Example of the request
{
"session": "c96fe83d-366c-420c-9038-da0fae844f0c",
"test": true
}
Response
Before sending the response, Demo PSP removes:
- Expired cards (
CardStatus=5
); - Those cards that can not be used for a transaction.
In case of successfully processed request the response contains the following parameters:
Parameter | Type | Description |
---|---|---|
card_list | array | A card list with card parameters. |
card_holder * required |
string | A cardholder name. Use only Latin letters, digits, gaps, and a dash. |
token * required |
string | A Masterpass card token. |
date * required |
string | A date on which the card was added. |
expiry_date * required |
string | An expiration date. |
pan_mask * required |
string | The first 6 and last 4 digits of the card. |
card_status * required |
integer | A card status. Possible values: 0 - Inactive. The card is not active. 1 - Active. The card is active. 2 - CVC2Always. For this CardStatus, you need to check CVC2. Active Suspended card 5 - Expired. The card was expired. |
is_recurring * required |
boolean | If the payment is recurring, set to true . Otherwise, false . |
card_name * required |
string | A card name. Use only Russian/Latin letters, gaps, a dash, *_-+, currency symbols. |
comment1 | string | Comment field 1. |
comment2 | string | Comment field 2. |
comment3 | string | Comment field 3. |
Example of the response if the user has cards in Masterpass
{
"card_list": [
{
"card_holder": "Masterpass",
"token": "8358d402-1111-1111-1111-9dc9811debe",
"expiry_date": "02/21",
"pan_mask": "511111xxxxxx8278",
"card_status": 2,
"is_recurring": false,
"card_name": "My card"
}
]
}
Example of the response if the user does not have cards in Masterpass
{
"card_list": []
}
In case of an error the response contains the following parameters:
Parameter | Type | Description |
---|---|---|
status * required |
string | A response status. |
error_code * required |
integer | An error code. |
error * required |
string | An error message. |
Error codes
If errors occur, use the following error_code
description to detect the reason.
Error code | Description | Comment |
---|---|---|
0 | None | Successful completion. |
2 | Api not allowed | Method call is prohibited after exceeding the allowed number of requests. |
8 | No user was found by the passed session | А non-existing session was transferred or the session has expired. Session should be re-opened. |
35 | Wrong params | The request was sent with an incorrect or incomplete set of parameters. |
Example of the response while an error occurred
{
"status": "failed",
"error": "Masterpass error response",
"error_code": 8
}
Get a card from Masterpass
Before you start
Before you get a new card from Masterpass, get a list of cards.
The method is used for every transaction to get up-to-date information about the card.
For recurring payments by token, the method is called automatically by Demo PSP.
Request
Send a POST
request to https://demo-gateway.begateway.com/masterpass/get_card
with the following parameters:
Parameter | Type | Description |
---|---|---|
token * required |
string | A Masterpass token (from a request of getting the list of cards) |
amount * required |
integer | A transaction amount in minimal currency units, for example $32.45 must be sent as 3245 |
session * conditionally required |
string | A user session ID. Required for non-recurrent card payments. |
currency * required |
string | A currency in ISO-4217 format, for example USD. |
test | boolean | If the operation is a test one, set to true . Otherwise, false . |
Example of the request
{
"session": "a6fd8624-8060-46b3-b343-7a93126fd57f",
"token": "2887f05c-ff7e-4e67-90e6-7d5e75abc036",
"amount": 10000,
"currency ": "USD",
"test": true
}
Response
In case of an error the response contains the following parameters:
Parameter | Type | Description |
---|---|---|
credit_card | object | Card data |
stamp * required |
string | Card hash. |
brand * required |
string | Card brand name. |
last_4 * required |
integer | Last 4 digits of the card number. |
first_1 * required |
integer | First digit of the card number. |
bin * required |
integer | BIN card number. |
issuer_country * required |
string | Card issuer country. |
issuer_name * required |
string | Card issuer name. |
product * required |
string | Card brand name. |
exp_month * required |
integer | Expiration Month. 2 digits. |
exp_year * required |
integer | Expiration Year. Last 2 digits. |
token_provider * required |
string | The token provider. Possible values or null . |
token * required |
string | Card token in the Demo PSP system. |
holder * required |
string | CardHolder name: letters should be only latin, digits, gaps, dash. |
recommendation * required |
integer | Checks recommended by Masterpass (not obligatory). Possible values: 0 - None;1 - CVC2 check;2 - 3DS check;3 - 3DS and CVC2 or CVC2 check;4 - 3DS and CVC2 check. |
required * required |
integer | Checks required by Masterpass (mandatory actions). Possible values:0 - None;1 - CVC2 check;2 - 3DS check;3 - 3DS and CVC2 or CVC2 check;4 - 3DS and CVC2 check. |
Example of the successful response
{
"credit_card": {
"holder": "JOHN DOE",
"stamp": "80b274398e413d7bddd4d7df8c9b8aa1f9b0a9233bfb7b9cb6de16d06ea31144",
"brand": "visa",
"last_4": "0019",
"first_1": "4",
"bin": "400555",
"issuer_country": null,
"issuer_name": null,
"product": null,
"exp_month": 10,
"exp_year": 2026,
"token_provider": null,
"token": "4d9e681b-498f-4f68-a4cd-89018a381c70"
},
"recommendation": 0,
"required": 0
}
In case of an error the response contains the following parameters:
Parameter | Type | Description |
---|---|---|
status * required |
string | A response status. |
error_code * required |
integer | An error code. |
error * required |
string | An error message. |
Error codes
If errors occur, use the following error_code
description to detect the reason.
Error code | Description | Comment |
---|---|---|
0 | Successful completion. | |
1 | The service is not available for this card/user. | The current user is blacklisted. It is recommended to update the list of cards by calling the GetCards method or let the user save a new card |
2 | Card is not activated. | Card details in this status cannot be received via the GetCard method. It is recommended to update the list of cards by calling the GetCards method or let the user save a new card. |
3 | The card was not found by the token. | It is recommended to update the list of cards by calling the GetCards method or let the user save a new card. |
5 | Customer with this phone number not found. | - |
12 | This transaction is marked as fraud. | - |
15 | Merchant with such a name and password not found. | The required Merchant field was not transferred in the request, or the Merchant with the same name was not found. |
16 | Session for the card not found, and it is not recurrent. | A non-existing session was transferred, or the session has expired. |
17 | Amount <= 0 | The value of the Amount parameter should be strictly greater than 0 |
19 | Wrong params. | The required parameter Amount is not transferred in the request, empty field or contains something other than numbers. |
44 | API_NOT_ALLOWED | Certificate not found or certificate expired or signing error. |
Example of the error response
{
"status":"failed",
"error":"Masterpass error response",
"error_code":16
}
Get a card from Masterpass using a Demo PSP token
Before you start
Before you get card data from Masterpass using a Demo PSP token, open a user session.
The method is used for every transaction initiated by a customer to get up-to-date information about the card tokenized by Demo PSP.
For recurring payments by token, the method is called automatically by Demo PSP.
Request
Send a POST
request to https://demo-gateway.begateway.com/masterpass/get_saved_card
with the following parameters:
Parameter | Type | Description |
---|---|---|
session * conditionally required |
string | User session ID. Required for non-recurrent card payments. |
credit_card_token * required |
string | Demo PSP token (from a response to a card tokenization request). |
amount * required |
integer | A transaction amount in minimal currency units, for example $32.45 must be sent as 3245. |
currency * required |
string | Currency in ISO-4217 format, for example USD. |
test | boolean | If the operation is a test one, set to true . Otherwise, false . |
Example of the request
{
"session": "5cb1ed91-8755-4a9c-89a0-c69899b36f6f",
"credit_card_token": "639c0b58-118e-44f6-ad8c-623592710ba",
"amount": 100,
"currency": "USD",
"test": true
}
Response
Parameter | Type | Description |
---|---|---|
credit_card | object | Card data. |
stamp * required |
string | Card hash. |
brand * required |
string | Card brand name. |
last_4 * required |
integer | The last 4 digits of the card number. |
first_1 * required |
integer | The first digit of the card number. |
bin * required |
integer | A BIN card number. |
issuer_country * required |
string | A card issuer country. |
issuer_name * required |
string | A card issuer name. |
product * required |
string | A card brand name. |
exp_month * required |
integer | A card expiration month. 2 digits. |
exp_year * required |
integer | A card expiration year. Last 2 digits. |
token_provider * required |
string | A token provider. |
token * required |
string | A card token in the Demo PSP system. |
holder * required |
string | A cardholder name. Use only Latin letters, digits, gaps, a dash. |
recommendation * required |
integer | Checks recommended by Masterpass (not obligatory). Possible values: 0 - None 1 - CVC2 check 2 - 3DS check 3 - 3DS and CVC2 or CVC2 check 4 - 3DS and CVC2 check. |
required * required |
integer | Checks required by Masterpass (mandatory actions). Possible values:0 - None;1 - CVC2 check;2 - 3DS check;3 - 3DS and CVC2 or CVC2 check;4 - 3DS and CVC2 check. |
Example of the successful response
{
"credit_card": {
"holder": "John Doe",
"stamp": "b3839d334ba40e89168d60cd9f9d1390aee3fe67dd4d5c41adbf3998043eaef8",
"brand": "visa",
"last_4": "0000",
"first_1": "4",
"bin": "420000",
"issuer_country": null,
"issuer_name": null,
"product": null,
"exp_month": 5,
"exp_year": 2026,
"token_provider": null,
"token": "639c0b58-118e-44f6-ad8c-623592710ba5"
},
"recommendation": 0,
"required": 0
}
Example of the error response
{
"status": "failed",
"error": "Params validation error",
"message": "No credit card found"
}
Make a payment by a card linked to Masterpass
Before you start
To make a payment with a card linked to Masterpass, receive card data from Masterpass and make a payment with the received Demo PSP token.
If the payment is recurring, it is not necessary to open a user session.
A Masterpass section should be added to the current payment request and the session
value should be specified.
Request
Send a payment request with the received Demo PSP token. Add the parameters below to the request.additional_data
object of the payment request.
Parameter | Type | Description |
---|---|---|
additional_data | object | Section of additional payment details. |
masterpass | object | A Masterpass section. |
params * required |
object | A section of Masterpass parameters. |
session * required |
string | A Masterpass user session ID. |
Example of the request
{
"request": {
"amount": 100,
"currency": "USD",
"description": "www",
"tracking_id": "masterpass_test_by_token",
"billing_address": {
"first_name": "John",
"last_name": "Doe",
"country": "US",
"city": "Denver",
"state": "CO",
"zip": "96002",
"address": "1st Street"
},
"credit_card": {
"token": "03d65020-07c4-4987-b96a-72ec9727ac1f",
"verification_value": 123
},
"additional_data": {
"masterpass": {
"params": {
"session": "037ead94-b11c-4dff-ad73-9e8a414ceb80"
}
}
},
"customer": {
"ip": "127.0.0.1",
"email": "email@example.com",
"birth_date": "1998-01-31"
},
"test": true
}
}
Response
Example of the response
{
"transaction": {
"uid": "9707-af6046bd28",
"status": "failed",
"amount": 100,
"currency": "USD",
"description": "www",
"type": "payment",
"payment_method_type": "credit_card",
"tracking_id": "masterpass_test_by_token",
"message": "Payment was declined",
"test": true,
"created_at": "2021-02-12T12:19:15.314Z",
"updated_at": "2021-02-12T12:19:20.541Z",
"paid_at": "2021-02-12T12:19:20.520Z",
"expired_at": null,
"closed_at": null,
"settled_at": null,
"manually_corrected_at": null,
"language": "en",
"redirect_url": "https://demo-gateway.begateway.com/process/9707-af6046bd28",
"credit_card": {
"holder": "JOHN DOE",
"stamp": "80b274398e413d7bddd4d7df8c9b8aa1f9b0a9233bfb7b9cb6de16d06ea31144",
"brand": "visa",
"last_4": "0019",
"first_1": "4",
"bin": "400555",
"issuer_country": null,
"issuer_name": null,
"product": null,
"exp_month": 10,
"exp_year": 2026,
"token_provider": null,
"token": "03d65020-07c4-4987-b96a-72ec9727ac1f"
},
"receipt_url": "https://demo-backoffice.begateway.com/customer/transactions/9707-af6046bd28/86e2642265417ab4f4d9102f3092b29dd7ace5a0a925727f9920f0b165e40111",
"id": "9707-af6046bd28",
"additional_data": {
"masterpass": {
"params": {
"session": "037ead94-b11c-4dff-ad73-9e8a414ceb80"
},
"result": {
"status": "successful",
"message": "Postback successfully finished."
}
}
},
"payment": {
"auth_code": "654321",
"bank_code": "10",
"rrn": "999",
"ref_id": "777888",
"message": "Payment was declined",
"amount": 100,
"currency": "USD",
"billing_descriptor": "test descriptor",
"gateway_id": 288,
"status": "failed"
},
"avs_cvc_verification": {
"avs_verification": {
"result_code": null
},
"cvc_verification": {
"result_code": null
}
},
"customer": {
"ip": "127.0.0.1",
"email": "email@example.com",
"device_id": null,
"birth_date": "1998-01-31"
},
"billing_address": {
"first_name": "John",
"last_name": "Doe",
"address": "1st Street",
"country": "US",
"city": "Denver",
"zip": "96002",
"state": "CO",
"phone": null
}
}
}
Error codes
If errors occur, use the following error_code
description to detect the reason.
Error code | Description | Comment |
---|---|---|
0 | Successful completion | |
1 | The service is not available for this card/user | The current card is blacklisted. It is recommended to update the list of cards by calling the GetCards method or let the user save a new card. |
2 | Card is not activated | Card details in this status cannot be received via GetCard method. It is recommended to update the list of cards by calling the GetCards method or let the user save a new card. |
3 | The card was not found by the token | It is recommended to update the list of cards by calling the GetCards method or let the user save a new card. |
5 | Customer with this phone number not found | - |
12 | This transaction is marked as fraud | - |
15 | Merchant with such a name and password not found | The required Merchant field was not transferred in the request, or the Merchant with the same name was not found |
16 | Session for the card not found and it is not recurrent | A non-existing session was transferred or the session has expired |
17 | Amount <= 0 | The value of the Amount parameter should be strictly greater than 0 |
19 | Wrong params | The required parameter Amount is not transferred in the request, empty field or contains something other than numbers. |
44 | API_NOT_ALLOWED | Certificate not found or certificate expired or signing error. |
Remove a card from Masterpass
Before you start
Before you remove a card from Masterpass, get a list of cards from Masterpass.
Request
Send a POST
request to https://demo-gateway.begateway.com/masterpass/delete_card
with the following parameters:
Parameter | Type | Description |
---|---|---|
token * required |
string | A Masterpass card token. |
session * required |
string | A Masterpass user session ID. |
test | boolean | If the operation is considered as a test one, set to true . Otherwise, false . |
Example of the request
{
"session": "d1d88fb8-1bf1-4c82-9c8b-00c9d887d821",
"token": "07be2846-aa35-480c-b1f8-a01d8674fadb",
"test": true
}
Response
Parameter | Type | Description |
---|---|---|
status * required |
string | Result of card removal in Masterpass. Possible values: successful ,failed . |
error_code | integer | Error code. |
error | string | Error message. |
Error codes
If errors occur, use the following error_code
description to detect the reason.
Error code | Description | Comment |
---|---|---|
0 | Successful completion | |
1 | Access denied | Merchant does not have the right to call this method |
5 | Card not found | Card with a token was not found. For example, it has been removed from the Masterpass. It is recommended to update the list of cards by calling GetCards methods or let the user save a new card. |
8 | No user was found by the passed session | А non-existing session was transferred or the session has expired. Session should be re-opened. |
20 | Internal error | Internal system error, additional check with Masterpass command required |
30 | Invalid Token card for this request | Mandatory parameter Token is not transferred, empty field or gaps is transferred |
35 | Wrong params | The request was sent with an incorrect or incomplete set of parameters. |
Example of the successful response
{
"status": "successful"
}
Example of the error response
{
"status": "failed",
"error": "Masterpass error response",
"error_code": 8
}