Request structure

Request for authorization hold

There are several things you need to consider when issuing requests:

1. The request is sent by using POST (HTTP) method to one of the following endpoints:
   • when indicating full card details—/v2/payment/card/auth,
   • when indicating an identifier instead of card details—/v2/payment/card/auth/saved,
   • when indicating a token instead of card details—/v2/payment/card/auth/token.
2. The following objects and parameters should be specified in the request:
   • Object general—general request identification information:
     • project_id—the project ID obtained from maxaa
     • payment_id—payment ID unique within the project
     • signature—signature created after you specify all the required parameters. For more information about signature generation, see Signature generation and verification
   • Object customer—customer information:
     • ip_address—IP address
     • id—the ID of the customer within the merchant project
   • Object payment—payment information:
     • amount—payment amount in minor currency units without any decimal point or comma except for cases where the currency does not have any minor currency units. If the currency has no minor units (that is, the number of digits for minor currency units is zero), then you must set this parameter to the amount in the major currency units. For the information on whether the currency has any minor units, see Currency codes.
     • currency—payment currency in the ISO-4217 alpha-3 format
3. The request should contain the following customer's payment card information:
   • when indicating complete card credentials—the following data in the card object:
     • pan—card number
     • year—year of expiration date
     • month—month of expiration date
     • card_holder—cardholder first and last names (as indicated on the card)
     • cvv—card verification code (as indicated on the card)
   • when indicating the identifier—the identifier which is associated with the card credentials in the payment platform in the saved_account_id parameter, and the card verification code in the cvv parameter
   • when indicating the token—token in the token parameter and the card verification code in the cvv parameter.
4. The request should contain the return_url object with the addresses for redirecting the customer to the web service:
   • success—the URL for redirecting the customer after the payment is completed;
   • decline—the URL for redirecting the customer after the payment is declined.
5. In case it is needed tot transfer funds to a merchant e-wallet, the object customer must contain the following additional parameters:
   • first_name—first name
   • last_name—last name
   • address—address (street, house number)
   • email—email
   • city—city of residence (town, village, etc.)
   • state—region of residence (state, county, canton, etc.)
6. If required, you can also add any other additional parameters Gate supports.

Thus, to perform a two-step payment by a payment card, the request must include project and payment IDs, signature, IP address of the customer, currency and amount of payment, as well as information about the payment card, as shown in the following example:

{
  "general": {
      "project_id": 42,
      "payment_id": "456789",
      "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
  },
  "customer": {
      "ip_address": "248.121.176.220",
      "id": "customer_12"
  },
  "payment": {
      "amount": 400000,
      "currency": "USD"
  },
  "return_url": {
        "success": "http://example.com/return",
        "decline": "http://example.com/decline"
  },
//when indicating complete card credentials:
  "card": {
      "pan": "4242424242424243",
      "year": 2025,
      "month": 8,
      "card_holder": "JOHN SMITH",
      "cvv": "123"
  }

//when indicating the identifier of a stored payment card:
    "saved_account_id": 2345678,
    "cvv": "123"

//when indicating the token of a stored payment card:
    "token": "f365bb1729f9b72fd9c09703a751c979f3becc679f29c3e35c91d18070d15654",
    "cvv": "123"   
}

Request for debiting of authorized amount

The request is sent by using POST (HTTP) method to the following endpoint /v2/payment/card/capture and must contain the following objects and parameters:

• Object general—general request identification information:
  • project_id—the project ID obtained from maxaa
  • payment_id—payment ID unique within the project
  • signature—signature created after you specify all the required parameters. For more information about signature generation, see Signature generation and verification
• If required, you can also add any other additional parameters Gate supports.

Thus, the correct request for debiting of authorized amount must include project and payment IDs and signature.

{
    "general": {
        "project_id": 42,
        "payment_id": "456789",
        "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
    }
}

Request for release of authorized amount

The request is sent by using POST (HTTP) method to the following endpoint /v2/payment/card/cancel and must contain the following objects and parameters:

• Object general—general request identification information:
  • project_id—the project ID obtained from maxaa
  • payment_id—payment ID unique within the project
  • signature—signature created after you specify all the required parameters. For more information about signature generation, see Signature generation and verification
• If required, you can also add any other additional parameters Gate supports.

Thus, the correct request for releasing of authorized amount must include project and payment IDs and signature.

{
    "general": {
        "project_id": 42,
        "payment_id": "456789",
        "signature": "v7KNMpfogAxwRIL9tVftZ1ZZ5D/aZAeb0VMdeR+CqGrNxYyilUwSm...=="
    }
}