One-step purchase

The request structure described in this section is applicable to one-step purchases with payment cards. Listed below are the requirements to payment request structure:

1. The request is sent by using POST (HTTP) method to one of the following endpoints:
   • /v2/payment/card/sale—when the request contains the complete card details
   • /v2/payment/card/sale/saved—when the request contains the identifier instead of card details
   • /v2/payment/card/sale/token—when the request contains the card token instead of the card details
2. The following objects and parameters must be specified in the request:
   • Object general—general request identification information:
     • project_id—project ID you obtained from Monetix
     • 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 units
     • currency—payment currency in the ISO-4217 alpha-3 format
3. The request should contain the following customer payment card information:
   • when specifying complete card details—the following information is required in the card object:
     • pan—card number
     • year—year of expiration date
     • month—month of expiration date
     • card_holder—cardholder's first and last name (as indicated on the card)
     • cvv—card verification code (CVV), as indicated on the card

       The cvv parameter is not required and not passed in payment requests for cards with no CVV. For more information whether the cvv parameter is optional, contact your key account manager.

   • when indicating the identifier—the following information is required: the identifier which is associated with the card details in the payment platform in the saved_account_id parameter and the card verification code in the cvv parameter provided the card has a verification code (CVV).

     The cvv parameter is not required and not passed in payment requests for cards with no CVV. For more information whether the cvv parameter is optional, refer to your key account manager.

   • when indicating the token—the following information is required: token in the token parameter and the card verification code in the cvv parameter—provided the cvv parameter is supported for the card.

     The cvv parameter is not required and not passed in payment requests for cards with no CVV. For more information whether the cvv parameter is optional, refer to your key account manager.

4. The request must contain the return_url object with the addresses for redirecting the customer to your system:
   • success—the URL for redirecting the customer after the payment is completed;
   • decline—the URL for redirecting the customer after the payment is declined.
   • return—the URL to redirect the customer to when they prematurely terminate the payment. This URL is also used if the success and decline parameters are not specified in the request.
5. Depending on specific regional requirements and requirements of providers and payment systems, you may be required to add the following additional user information:
   • first_name—first name
   • last_name—last name
   • middle_name—middle name (or patronymic)
   • day_of_birth—birth date
   • phone—phone number
   • email—email address
   • zip—post code of residence location
   • address—address (street, house number)
   • city—city of residence (town, village, etc.)
   • district—district of residence
   • state—region of residence (state, county, canton, etc.)
   • avs_post_code—post code registered with issuer as customer's actual post code
   • avs_street_address—street and house number registered with issuer as customer's actual address

   If some parameters are missing from your request, the payment platform may require you to submit additional payment information. For more information about submitting additional payment information, see Submission of additional payment information. For details what parameters are required in your case, refer to your account manager at Monetix.

6. If required, you can also add any other additional parameters Gate supports.

Here is an example of a payment request:

{
  "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 details:
  "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"   
}