Payout by token

Overview

This section covers payout by a token using Gate.

Token is a unique string of 64 characters associated within the payment platform with a certain payment card. Tokens contain no confidential information and can be stored in your system without violation of any payment card data security standards. For more information about using tokens, see Tokens.

The payout workflow

To perform a payout by a token using Gate your system is required to do the following:

  1. Send the payout request with all the required parameters and signature to the Rocketpay URL.
  2. If necessary, submit additional payment information.

    For more information about submitting additional payment information, see Submission of additional payment information.

  3. Accept the callback with the payout result from the payment platform.

The following diagram provides the information about the basic payout processing case (without submitting additional payment information).



Figure: Payout flow

  1. The customer initiates a payout in your system.
  2. Your system sends the payout request to the payment platform by using Gate.
  3. The payment platform receives the payout request.
  4. The payment platform checks whether the request contains all the required parameters and correct signature.
  5. The payment platform sends you a response in which it acknowledges your request and provides the request validation result. (For more information about the response format, see Response structure.)
  6. The payment platform processes the request and forwards it to the provider service.
  7. The provider service processes the payout.
  8. The provider service informs the payment platform about the payout result.
  9. The payment platform sends the callback with the payout result to your system.
  10. Your system sends the payout result to the customer.

The sections that follow discuss in more details the request structure and the parameters to be used in requests for payouts, as well as provide information about the callbacks with the payout results.

Request

This section provides the instructions on how to request a payout by token.

HTTP request method POST
Request body format JSON
API endpoint /v2/payment/card/payout/token
Full API endpoint specification /v2/payment/card/payout/token
Table 1. Basic parameters of payout request

strictly required—the parameter must be in the initial request.

optional—the parameter is optional but adding it to the request either makes the payment process more customer-friendly or helps to increase the percentage of successful payments.

required conditionally—parameter is required depending on the situation. See the parameter description for details
Object Parameter Description

general
object
strictly required

project_id
integer
strictly required

Project ID you obtained from Rocketpay when integrating.

Example: 123

payment_id
string
strictly required

Payment ID unique within your project.

Example: payment_47

signature
string
strictly required

 Signature created after you've specified all the request parameters. For more information about signature generation, see Signature generation and verification.

customer
object
strictly required

id
string
strictly required

Unique ID of the customer within your project.

Example: customer_123

first_name
string
strictly required

Customer's first name.

Example: John

middle_name
string
strictly required

Customer's middle name.

Example: Paul

last_name
string
strictly required

Customer's last name.

Example: Doe

ip_address
string
strictly required

IP address of the customer's device.

Example: 198.51.100.47

payment
object
strictly required

amount
integer
strictly required

Payout amount in minor currency units without any decimal point or comma except for the cases when the currency doesn't have any minor currency units. If the currency doesn't have any minor units (i.e. the number of digits for minor currency units is zero), set this parameter to the amount in the major currency units. To check whether the currency has any minor units, see Currency codes.

Example: 100,00 USD must be sent as 10000

currency
string
strictly required

Code of the purchase currency in the ISO-4217 alpha-3 format.

Example: USD

token
string
strictly required

   A token of the customer's payment card. A token is a unique string of 64 characters associated with a specific bank card.

Example: f365bb1729f9b72fd9c79f3becc679f29c3e35c91d070d15654

For more information see Tokens

card
object
required conditionally

card_holder
string
required conditionally

Cardholder's first and last name (as indicated on the card).

This parameter is strictly required if the payout is performed by the token that was created without using the cardholder's name.

Example: JOHN DOE
You can also add any other optional parameters to the purchase request, if necessary. For the list of all the parameters available in Gate, see API Reference.
Note: The first name, the middle name (or patronymic), and the last name of the customer must be specified for all cards with the exception of those issued in the Russian Federation. For the latter, passing these parameters is not required.

Figure: Example of the data from the request for a payout by a token

{
    "general": {
        "project_id": 123,
        "payment_id": "payment_47",
        "signature": "1wR1YgDoDlJppOdLzFOFK...Y4YonbWmspbFh7x1o1ut5PxxTIJfQ=="
    },
    "customer": {
        "id": "customer_123",
        "ip_address": "198.51.100.47"
    },
    "payment": {
        "amount": 10000,
        "currency": "USD"
    },
    "token": "pkmawa3khb7wninntq8g8q3592fjjxwvzfebwbegqkl1c16akpgo6sgxac6wulz7"
}

Callback

The payment platform returns the payout result in a callback. For the information about the callback structure, see Callbacks in Gate.

The following is the example of a callback with information about successful 100.00 USD payout made to the card number 553691******0802 of the customer_123 customer in the 123 project.

Figure: Example of the data from a successful payout callback

{
    "project_id": 123,
    "payment": {
        "id": "payment_47",
        "type": "payout",
        "status": "success",
        "date": "2019-06-24T11:08:49+0000",
        "method": "card",
        "sum": {
            "amount": 10000,
            "currency": "USD"
        },
        "description": "payout"
    },
    "account": {
        "number": "553691******0802"
    },
    "customer": {
        "id": "customer_123"
    },
    "operation": {
        "id": 14,
        "type": "payout",
        "status": "success",
        "date": "2019-06-24T11:08:49+0000",
        "created_date": "2019-06-24T11:07:42+0000",
        "request_id": "71228f54d21e776a481",
        "sum_initial": {
            "amount": 10000,
            "currency": "USD"
        },
        "sum_converted": {
            "amount": 10000,
            "currency": "USD"
        },
        "provider": {
            "id": 1496,
            "payment_id": "60-1c6072de6000",
            "date": "2019-06-24T11:08:47+0000",
            "auth_code": ""
        },
        "code": "0",
        "message": "Success"
    },
    "signature": "+GTEzb3Xw4A9Ap8q/LE8TyyJM+MEXXja28RXtr8v2EITaK4UzSg...=="
}

The following is the example of a callback for a payout rejected due to the maximum payout limit being exceeded.

Figure: Example of a declined payout callback

{
    "project_id": 123,
    "payment": {
        "id": "payment_47",
        "type": "payout",
        "status": "decline",
        "date": "2019-06-24T11:08:49+0000",
        "method": "card",
        "sum": {
            "amount": 10000,
            "currency": "USD"
        },
        "description": "payout"
    },
    "account": {
        "number": "553691******0802"
    },
    "customer": {
        "id": "customer_123"
    },
    "operation": {
        "id": 14,
        "type": "payout",
        "status": "decline",
        "date": "2019-06-24T11:08:49+0000",
        "created_date": "2019-06-24T11:07:42+0000",
        "request_id": "71228f54d21e776a481",
        "sum_initial": {
            "amount": 10000,
            "currency": "USD"
        },
        "sum_converted": {
            "amount": 10000,
            "currency": "USD"
        },
        "provider": {
            "id": 1496,
            "payment_id": "60-1c6072de6000",
            "date": "2019-06-24T11:08:47+0000",
            "auth_code": ""
        },
        "code": "3104",
        "message": "Payment Constraint Invalid Payout Amount"
    },
    "signature": "+GTEzb3Xw4A9Ap8q/LE8TyyJM+MEXXja28RXtr8v2EITaK4UzSg...=="
}

Related links