Payout by card

Overview

This section covers payout by card using Gate. To perform a payout by a card number, you have to specify and submit payment card details, which means you must comply with PCI DSS (Payment Card Industry Data Security Standards).

The payout workflow

To perform a payout by a card number 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 a card number.

HTTP request method POST
Request body format JSON
API endpoint /v2/payment/card/payout
Full API endpoint specification /v2/payment/card/payout
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
optional

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

card
object
strictly required

pan
string
strictly required

Card number.

Example: 1122334455667788

year
integer
required conditionally

Year of expiration date.

Reach out to your Rocketpay key account manager to make sure if this parameter is required in your case.

Example: 2025

month
integer
required conditionally

Month of expiration date.

Reach out to your Rocketpay key account manager to make sure if this parameter is required in your case.

Example: 8

card_holder
string
strictly required

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

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 the card number

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

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