Skip to content

Card Transfer

PX Integration option

Payment Flow

  1. The customer clicks Pay on the merchant's website.
  2. The merchant displays a page with the bank details, transaction amount and the number of the card, to which the payment must be made.
  3. The customer copies the information from the page and makes a payment within a 15-minute timeframe using an application or an internet banking option of their choice.
  4. To speed up the transaction processing, the merchant may add a button for payment confirmation. Clicking this button after the payment will send a transaction confirmation request. This step is optional.
  5. The merchant receives a webhook notification with the transaction status.
  6. If the transaction status is successful, the amount is credited to the customer's account balance on the merchant's website.
  7. If the customer makes a payment later than the designated 15-minute timeframe, the returned transaction status is failed.
  8. If the customer's balance hasn't been updated on the merchant's website but they made the payment, they should request the payment proof from the merchant providing the evidence documents of the money withdrawal from their account.
  9. The merchant sends the payment proof request to Demo PSP attaching the file with all the evidence documents provided by the customer. Each evidence document must be placed on a separate page within the attached file. Payment proof can only be requested for failed payments. Proof requests with "payment_status": "pending" or "payment_status": "successful" will be declined.
  10. Below are the possible scenarios for after the proof request has been sent:
Statuses in the status query response Description
"payment_status": "successful"

"proof_status": "successful"		 Proof request is approved. The webhook notification with the updated payment status and payment amount will be sent to the merchant.
"payment_status": "failed"

"proof_status": "failed"		 Proof request is declined. The webhook notification with failed statuses for both objects will be sent to the merchant.
"payment_status": "pending" or "payment_status": "failed"

"proof_status": "successful"		 Proof request is being processed. The merchant needs to wait until the payment transaction is successful (either in the response to the status query or in the webhook notification) before finalizing the transaction in their system.

Note

The merchant must not send another payment proof request unless they receive the payment webhook notification after the previous payment proof request. The payment proof request processing takes from 1 hour to 2 business days. The maximum number of proof requests per payment is 3.

Payment

Request

Send a payment request with the following additional parameters:

Parameter Type Description
method object A section of the payment method.
type * required
 string card_transfer
channel * required
 string Specify one of the following values:
RAIFFEISEN;
TINKOFF;
SBERBANK;
ANY
Note that this parameter value must be specified in capital letters.
customer object A section with the customer's details.
email * optional
 string The customer's email.
country * optional
 string The customer's billing country in the ISO 3166-1 alpha-2 format.
phone * optional
 string The customer's phone number.
device_id * optional
 string The customer's device ID.

Note

The value in the amount field must be an integer amount specified in minimal currency units. For example, 50000 (500 rubles).

Note

The amount value must be in the range from 50000 to 15000000 (500—150000 RUB).

Example of the request 
{
    "request": {
        "amount": 50000,
        "currency": "RUB",
        "description": "description",
        "test": true,
        "tracking_id": "11111111",
        "ip": "127.0.0.1",
        "language": "en",
        "notification_url": "https://merchant.ltd/notification",
        "customer": {
            "first_name": "John",
            "last_name": "Doe",
            "middle_name": "Mid",
            "country": "RU",
            "city": "Moscow",
            "zip": "101000",
            "address": "1st Street",
            "phone": "17777777777",
            "device_id": "12312312321fff67"
        },
        "method": {
            "type": "card_transfer",
            "channel": "ANY"
        }
    }
}
Response

The response will contain the following additional parameters:

Parameter Type Description
card_transfer object
mark * required
 string The code the customer needs to specify in the comment field if there is such a field in their banking option.
target_card * required
 string Card number to which the payment must be made.
expired_at * required
 string Time until which the payment must be made. Set in the ISO-8601 format: YYYY-MM-DDThh:mm:ssTZD, where YYYY – year (for example, 2019), MM – month (for example, 02), DD – day (for example, 09), hh – hours (for example, 18), mm – minutes (for example, 20), ss – seconds (for example, 45), TZD – time zone (+hh:mm or –hh:mm indicating an offset from UTC).
Example of the response 
{
    "transaction": {
        "uid": "cf5bdc19-f71a-4a4e-a20d-94465e3e9844",
        "type": "payment",
        "status": "pending",
        "amount": 50000,
        "currency": "RUB",
        "description": "description",
        "created_at": "2023-06-22T11:31:19Z",
        "updated_at": "2023-06-22T11:31:19Z",
        "method_type": "card_transfer",
        "receipt_url": "https://url.com",
        "payment": {
            "status": "pending",
            "gateway_id": 2904,
            "ref_id": "b5f6b23c-130e-4733-8ebf-a297c1746edc",
            "message": "Transaction was initialized."
        },
        "card_transfer": {
            "type": "card_transfer",
            "mark": "15FEBB2",
            "target_card": "1234567891234501",
            "expired_at": "2023-06-22T11:46:19Z",
            "bank_type": "ANY"
        },
        "customer": {
            "first_name": "John",
            "last_name": "Doe",
            "middle_name": "Mid",
            "country": "RU",
            "city": "Moscow",
            "zip": "101000",
            "address": "1st Street",
            "phone": "17777777777",
            "device_id": "12312312321fff67",
            "email": null,
            "ip": "127.0.0.1"
        },
        "message": "Transaction was initialized.",
        "tracking_id": "11111111",
        "test": true,
        "language": "en",
        "billing_address": {
            "first_name": "John",
            "last_name": "Doe",
            "middle_name": "Mid",
            "country": "RU",
            "city": "Moscow",
            "zip": "101000",
            "address": "1st Street",
            "phone": "17777777777",
            "device_id": "12312312321fff67"
        },
        "additional_data": {
            "payment_method": {
                "type": "alternative"
            }
        }
    }
}

Payment proof

Request

POST https://api.begateway.com/beyag/transactions/{uid}/proof

Parameter Type Description
request object
skip_duplicate_check boolean If false, declines a request if the request with the same uid was sent within 30 seconds prior to it. By default, set to false.
amount * required
 bigInteger Payment proof amount in minimal currency units without coins.
currency * required
 string (3) Transaction currency in the ISO-4217 alpha-3 code format.
document object
content_type *required
 string application/pdf
file_name *required
 string File name including the file extension.
file_size * required
 integer File size in bytes.
content * required
 string Payment proof documents, base64 encoded. Each evidence document must be placed on a separate page within the file. The original file must be in PDF format.
checksum *required
 string Payment proof amount, SHA256 encrypted.
Request example 
{
  "request": {
    "skip_duplicate_check": false,
    "amount": 322400,
    "currency": "RUB",
    "document": {
      "content_type": "application/pdf",
      "file_name": "3224.pdf",
      "file_size": 198149,
      "content": "cmVmCjE5Yzd2NwolJUVPRgo=",
      "checksum": "45EA3C910A727823079CF1E7DAB4B8BA"
    }
  }
}
Status query responses

After the proof request has been sent, the response to the status query will contain an object proof with 3 possible statuses: pending, failed or successful.

Once the proof request is processed, the merchant will get a webhook notification either with a failed status for both the payment and the proof request or with a successful status for both requests.

Example of status query response with the pending status for proof 
{
    "transaction": {
        "uid": "d17a3b46-1a49-4d0d-b814-b20f414d82ab",
        "type": "payment",
        "status": "failed",
        "amount": 100000,
        "currency": "RUB",
        "description": "tesdhgfljkdfhg;dfh",
        "created_at": "2023-08-16T05:59:40Z",
        "updated_at": "2023-08-16T07:35:09Z",
        "method_type": "card_transfer",
        "receipt_url": "https://demo-backoffice.begateway.com/customer/transactions/d17a3b46-1a49-4d0d-b814-b20f414d82ab/12f6a5a5677022c46745076308bf5c97557c6c75557666e8f690ce084936bd34?language=ru",
        "payment": {
            "status": "failed",
            "gateway_id": 2976,
            "ref_id": "c909f8ad-5b3e-4903-b08f-e209ced37950",
            "message": "Transaction was declined."
        },
        "card_transfer": {
            "mark": "160385A",
            "type": "card_transfer",
            "expired_at": "2023-08-16T06:14:41Z",
            "bank_type": "TINKOFF",
            "target_card": "9999999999999999"
        },
        "customer": {
            "email": "test@example.com",
            "phone": "56356464674",
            "country": "BY",
            "device_id": "f02ee44965442d87de97cf54bffb906f",
            "ip": null
        },
        "message": "Transaction was declined.",
        "tracking_id": "3e32451b-cb3a-4094-b40c-3e83883e2f4c",
        "test": false,
        "language": "ru",
        "paid_at": "2023-08-16T06:01:08Z",
      ...
        "proof": {
            "ref_id": "97be822d-6c34-4ead-9579-21a8f42a92e1",
            "gateway_id": 2976,
            "status": "pending",
            "message": "Proof was initialized."
        }
    }
}
Example of status query response with the successful status for proof 
{
    "transaction": {
        "uid": "d17a3b46-1a49-4d0d-b814-b20f414d82ab",
        "type": "payment",
        "status": "successful",
        "amount": 100000,
        "currency": "RUB",
        "description": "tesdhgfljkdfhg;dfh",
        "created_at": "2023-08-16T05:59:40Z",
        "updated_at": "2023-08-16T07:35:09Z",
        "method_type": "card_transfer",
        "receipt_url": "https://demo-backoffice.begateway.com/customer/transactions/d17a3b46-1a49-4d0d-b814-b20f414d82ab/12f6a5a5677022c46745076308bf5c97557c6c75557666e8f690ce084936bd34?language=ru",
        "payment": {
            "status": "failed",
            "gateway_id": 2976,
            "ref_id": "c909f8ad-5b3e-4903-b08f-e209ced37950",
            "message": "Transaction was successfully processed."
        },
        "card_transfer": {
            "mark": "160385A",
            "type": "card_transfer",
            "expired_at": "2023-08-16T06:14:41Z",
            "bank_type": "TINKOFF",
            "target_card": "9999999999999999"
        },
        "customer": {
            "email": "test@example.com",
            "phone": "56356464674",
            "country": "BY",
            "device_id": "f02ee44965442d87de97cf54bffb906f",
            "ip": null
        },
        "message": "Transaction was successfully processed.",
        "tracking_id": "3e32451b-cb3a-4094-b40c-3e83883e2f4c",
        "test": false,
        "language": "ru",
        "paid_at": "2023-08-16T06:01:08Z",
      ...
        "proof": {
          "ref_id": "f8casdf56-1e85-r456-9842-fasdfasdf",
          "gateways_id": 2985,
          "status": "successful",
          "message": "Proof was successfully processed."
        }
    }
}
Example of status query response with the failed status for proof 
{
    "transaction": {
        "uid": "d17a3b46-1a49-4d0d-b814-b20f414d82ab",
        "type": "payment",
        "status": "failed",
        "amount": 100000,
        "currency": "RUB",
        "description": "tesdhgfljkdfhg;dfh",
        "created_at": "2023-08-16T05:59:40Z",
        "updated_at": "2023-08-16T07:35:09Z",
        "method_type": "card_transfer",
        "receipt_url": "https://demo-backoffice.begateway.com/customer/transactions/d17a3b46-1a49-4d0d-b814-b20f414d82ab/12f6a5a5677022c46745076308bf5c97557c6c75557666e8f690ce084936bd34?language=ru",
        "payment": {
            "status": "failed",
            "gateway_id": 2976,
            "ref_id": "c909f8ad-5b3e-4903-b08f-e209ced37950",
            "message": "Transaction was declined."
        },
        "card_transfer": {
            "mark": "160385A",
            "type": "card_transfer",
            "expired_at": "2023-08-16T06:14:41Z",
            "bank_type": "TINKOFF",
            "target_card": "9999999999999999"
        },
        "customer": {
            "email": "test@example.com",
            "phone": "56356464674",
            "country": "BY",
            "device_id": "f02ee44965442d87de97cf54bffb906f",
            "ip": null
        },
        "message": "Transaction was declined.",
        "tracking_id": "3e32451b-cb3a-4094-b40c-3e83883e2f4c",
        "test": false,
        "language": "ru",
        "paid_at": "2023-08-16T06:01:08Z",
      ...
        "proof": {
            "ref_id": "f8casdf56-1e85-r456-9842-fasdfasdf",
            "gateways_id": 2985,
            "status": "failed",
            "message": "Proof was declined."
        }
    }
}

Transaction confirmation

Request

POST https://api.begateway.com/beyag/transactions/{uid}/confirm

Parameter Type Description
skip_duplicate_check boolean If false, declines a request if the request with the same uid was sent within 30 seconds prior to it. By default, set to false.
Response
Successful response example 
{
    "response": {
        "parent_uid": "2-310b0da80b", 
        "type": "confirm",
        "status": "successful", 
        "message": "Confirm was successfully processed",
        "created_at": "2023-05-11T12:04:59+03:00",
        "amount": 332400,
        "currency":"RUB"
    }
}
Response example with failed status 
{
    "response": {
        "parent_uid": "2-310b0da80b",
        "type": "confirm",
        "status": "failed",
        "message": "Confirm was failed",
        "created_at": "2023-05-11T12:04:59+03:00",
        "amount": 50,
        "currency": "RUB"
    }
}
Response example when the transaction is not found 
{
        "response": {
            "message": "Record not found",                
        }
}