Create a payment token

Before you use either the Overpay payment widget or the hosted payment page, you should create a payment token.

Request

Send a POST request to https://checkout.overpay.io/ctp/api/checkouts.

The request must:

• use HTTP Basic authentication with Shop ID and Secret Key;
• have the headers Content-Type: application/json, Accept: application/json and X-API-Version: 2;
• be UTF-8 encoded.

checkout object transaction_type required string Type of transaction or request that will be sent to gateway. Applicable values are authorization, payment, tokenization, and charge (for the charge request). attempts integer Number of payment attempts. The default is 1. dynamic_billing_descriptor string Dynamic billing descriptor. test boolean Set to true for a test transaction. Otherwise, false (default). iframe boolean When the value is true, if possible, open transitions to external services inside the widget. By default, set as false. order required object amount required integer Payment amount in minimal currency units, for example, $32.45 must be sent as 3245. currency required string Transaction currency in the ISO-4217 alpha-3 code format. For example, USD. description required string Order description. tracking_id string ID of your transaction or order. Please, use unique values for each transaction. expired_at string Date and time till a payment can be done. By default, a payment must be done within 24 hours upon a payment token creation. Format (ISO 8601): 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 или –hh:mm). additional_data object Section of additional information about the payment. recipient object Section with the payment recipient information. account_number string The identifier of the payment recipient's account. account_number_type string The format of the payment recipient's account identifier. Possible values: card, iban, bic, other. expected_bank_code string If this field contains a processing error, it will be sent as the value of the code parameter in the response. The parameters message and friendly_message will have the values corresponding to the specified error code. This logic applies only to test transactions. receipt_text array Text that will be added to the customer's mail and will be showed on success result page. Submit it as an array of strings, for example, ["First line", "Second line"]. contract array Array that consists of elements: recurring - Overpay returns a card token to use it for subsequent payments when the customer has no need to enter card data again. As for the initial payment, the customer should provide full card data including a CVC/CVV code, pass the 3-D Secure verification, and give consent to be charged regularly. oneclick - Overpay returns a card token to use it in the one-click payment scheme. Overpay opens a payment page with pre-filled card data to the customer. To complete a payment, the customer has to enter a CVC/CVV code and to pass the 3-D Secure verification; credit - Overpay returns a card token to use it for a payout transaction; card_on_file - Overpay returns a card token to save it to a customer profile and to use the token in time-to-time charges initiated by the customer or by your application. See card_on_file section below to understand what cases the contract type covers. avs_cvc_verification object AVS/CVC verification. card_on_file object It sets flags submitted to a payment network why and what you charged a previously saved card for. If no submitted default values of initiator and type are in use. initiator string merchant - (default) merchant initiated a card charge (for instance, for a car ride service). customer - customer initiated a card charge (for instance, customer confirmed and order and wanted to pay by a saved card). type string Used only in case additional_data.card_on_file.initiator is merchant. delayed_charge - (default) delayed charge posted to a card increment - merchant wants to charge additional amount above initially paid order (for instance, in case of upsale) resubmission - merchant wants to resubmit a transaction due to fail with a previous charge (for instance, no money on a card) reauthorization - merchant wants to refresh previously authorized amount (for instance, to continue to hold a money reserve on a card for future charges) no_show - merchant wants to charge a card when customer didn't come (for instance, no visit to a hotel) settings object auto_pay boolean By default false. If true and the request contains payment_method.credit_card.token, the response will contain a link to the checkout page. Opening the link will automatically trigger the transaction that will run using the provided token. As a result, the customer will be redirected to suсcess_url, decline_url, fail_url or return_url depending on the transaction result and the URLs provided in the request. The webhook notification with the transaction status will be posted to the notification_url. style object Section for customizing the design of the payment widget. save_card_toggle object Section for configuring the toggle shown on the payment widget. The toggle enables the option to save card data for future payments. display boolean If the parameter is true, the save card toggle should be displayed. This parameter has greater priority, than Display save card toggle on payment page parameter in shop settings in the Merchant back office. By default, set to true. customer_contract boolean true - the toggle stands for the customer's consent to provide the merchant with the customer's card data for subsequent payments. When the toggle is on, the system creates the card token and sends it out to the merchant. Otherwise, the card token is not provided. false - the toggle stands for the customer's consent to get the card data saved on the payment page. When the toggle is on, the system will autocomplete the card data for subsequent payments in the merchant's shop. Otherwise, the card data are not saved. By default, false. text string The parameter replaces the standard toggle name Save card to any Merchant text. hint string Hint text, described why the save card option is needed. another_card_toggle object Section for configuring the another card toggle. display boolean If the parameter is true, the toggle Рay with another card will be displayed on the widget. This parameter has greater priority, than Hide another card toggle on payment page parameter in shop settings in the Merchant back office. By default, set to true. return_url string URL to return the customer after transaction was complete. If set, then both success_url and decline_url are ignored. success_url string URL to return the customer to if a transaction was successful. decline_url string URL to return the customer to if a transaction was declined by bank. fail_url string URL to return the customer to if a transaction failed (due to an error, exception, etc.). You can query its status using the payment token and review response status and message parameters to evaluate why the transaction failed. cancel_url string URL to return the customer to if the customer cancels a transaction. notification_url string URL where notification about a transaction will be posted to. A notification request format is similar to a transaction response format. verification_url string auto_return string After a transaction completes, Overpay shows a transaction result page for specified number of seconds and then automatically returns the customer to one of your return URLs. If the parameter value is 0, then the customer will be automatically redirected without showing Overpay transaction result page. button_next_text string Customize the payment result page button text. language string Checkout page locale. English (en) is set by default. Possible values of language parameter. customer_fields object It controls the input fields for the customer details shown at the payment widget. Note: For card transactions, by default, the customer parameters submitted by the merchant in this request are not displayed on the widget. To display the submitted fields on the widget, include them either in the read_only array (non-editable) or in the visible array (editable). For alternative payment methods, by default, the customer parameters submitted by the merchant in this request are hidden on the widget. To display the submitted fields on the widget, include them in the visible array. read_only array Array which may consist of the values email, first_name, last_name, address, city, state, zip, phone, country, birth_date, taxpayer_id. Fields for the customer's data indicated in the array will be disabled at the payment widget. If email exists in the array then it must present in the customer section below, and it can't be empty. visible array Array which may consist of the values email, first_name, last_name, address, city, state, zip, phone, country and birth_date, taxpayer_id. Fields for the customer's data indicated in the array will be displayed at the payment widget. credit_card_fields object It controls the automatic filling of the cardholder name on the payment widget. holder string Cardholder name for automatic filling on the payment widget. read_only array Array which may consist only holder value. Blocks editing of the selected field. customer conditionally required object Section of the customer information. Contact the Tech Support Team to inquire what section parameters are required. email string The customer's email. first_name string The customer's first name. last_name string The customer's last name. address string The customer's billing address. city string The customer's billing city. state string The customer's two-letter billing state only if the billing address country is IN, US or CA. zip string The customer's billing ZIP or postal code. country string The customer's billing country in ISO 3166-1 alpha-2 format. phone string The customer's phone number. birth_date string The customer's date of birth in the ISO 8601 YYYY-MM-DD format. external_id string The customer's identifier in the merchant's system. taxpayer_id string The customer's taxpayer ID. payment_method object Section to set payment methods available to the customer and their parameters. By default, all enabled payment methods are available. types array Array of the available and enabled payment methods displayed to the customer on the payment page. Possible values: credit_card - a bank card payment erip - a payment via ERIP For other possible array values, see the value of the type parameter in the section of alternative payment methods. If the listed payment method requires additional parameter settings, then create an object with the key name set as the type of the payment method and internal parameters set as described in the alternative payment methods section. For example, for a payment method with the apm type and the channel parameter, add the following object: "apm": { "channel": "ONLINE" }`. Note! Apple Pay, Google Pay and Samsung Pay are displayed on the widget depending on the customer's device and browser types. See more here. excluded_types array Array of the payment types that will be excluded from the available payment methods on the payment page. If both payment_method.types and payment_method.excluded_types are sent in the request, the information from payment_method.types will be applied and payment_method.excluded_types will be ignored. excluded_brands array Array of card brands and digital wallets (apple_pay, google_pay, samsung_pay) that will not be displayed on the widget and will not be available to use for the transaction, even if they are available on the gateway. erip object Parameters to set up ERIP payment. Description of every parameter can be found here. order_id integer 12-digit order number in your system. account_number string Order number/ service/ agreement to get a payment via ERIP. service_no string ERIP service number. service_info array Array of strings to build a payment hint with the payment purpose description. credit_card object token string Card token. The tokenized data will be displayed on the payment page. travel object An optional section with travel related data.

Request example

{
  "checkout": {
    "test": true,
    "transaction_type": "payment",
    "attempts": 3,
    "settings": {
      "return_url": "http://127.0.0.1:4567/return",
      "success_url": "http://127.0.0.1:4567/success",
      "decline_url": "http://127.0.0.1:4567/decline",
      "fail_url": "http://127.0.0.1:4567/fail",
      "cancel_url": "http://127.0.0.1:4567/cancel",
      "notification_url": "http://your_shop.com/notification",          
      "button_next_text": "Back to the shop",
      "language": "en",
      "customer_fields" : {
        "visible" : ["first_name", "last_name"],
        "read_only" : ["email"]
      },
      "credit_card_fields": {
        "holder": "Rick Astley",
        "read_only": ["holder"]
      }
    },
    "payment_method": {
        "types": [
            "credit_card",
            "bank_transfer"
        ],
        "bank_transfer": {
            "account": "DE89370400440532013000"

        },
        "excluded_brands": [
            "visa",
            "google_pay"
        ]
    },
    "order": {
      "currency": "GBP",
      "amount": 4299,
      "description": "Order description"
    },
    "customer": {
      "address": "Baker street 221b",
      "country": "GB",
      "city": "London",
      "email": "jake@example.com"
    }
  }
}

Request example with additional receipt text and without redirect to result page

{
  "checkout": {
    "test": true,
    "transaction_type": "payment",
    "attempts": 3,
    "settings": {
      "return_url": "http://127.0.0.1:4567/return",
      "success_url": "http://127.0.0.1:4567/success",
      "decline_url": "http://127.0.0.1:4567/decline",
      "fail_url": "http://127.0.0.1:4567/fail",
      "cancel_url": "http://127.0.0.1:4567/cancel",
      "notification_url": "http://your_shop.com/notification",
      "auto_return": 0,
      "language": "en",
      "customer_fields" : {
        "visible" : ["first_name", "last_name"],
        "read_only" : ["email"]
      }
    },
    "order": {
      "currency": "GBP",
      "amount": 4299,
      "description": "Order description",
      "additional_data": {
        "receipt_text": ["First line", "Second line"]
      }
    },
    "customer": {
      "address": "Baker street 221b",
      "country": "GB",
      "city": "London",
      "email": "jake@example.com"
    }
  }
}

Request example with information about the sale of tickets and tour vouchers

{
  "checkout": {
    "test": true,
    "transaction_type": "payment",
    "attempts": 3,
    "settings": {
      "return_url": "http://127.0.0.1:4567/return",
      "success_url": "http://127.0.0.1:4567/success",
      "decline_url": "http://127.0.0.1:4567/decline",
      "fail_url": "http://127.0.0.1:4567/fail",
      "cancel_url": "http://127.0.0.1:4567/cancel",
      "notification_url": "http://your_shop.com/notification",
      "auto_return": 3,          
      "button_next_text": "Back to the shop",
      "language": "en",
      "customer_fields" : {
        "visible" : ["first_name", "last_name"],
        "read_only" : ["email"]
      }
    },
    "order": {
      "currency": "GBP",
      "amount": 4299,
      "description": "Order description"
    },
    "customer": {
      "address": "Baker street 221b",
      "country": "GB",
      "city": "London",
      "email": "jake@example.com"
    },
    "travel": {
      "airline": {
        "agency_code": "03",
        "agency_name": "Corel travel",
        "ticket_number": "390 5241 025377 1",
        "booking_number": "DKZVUA",
        "restricted_ticked_indicator": "0",
        "legs": [
          {
            "airline_code": "B2",
            "stop_over_code": "X",
            "flight_number": "A3 971",
            "departure_date_time": "2014-05-26T05:15:00",
            "arrival_date_time": "2014-05-26T07:30:00",
            "originating_country": "RU",
            "originating_city": "Moscow",
            "originating_airport_code": "DME",
            "destination_country": "Greece",
            "destination_city": "Athens",
            "destination_airport_code": "ATH",
            "coupon": "coupon code",
            "class": "C"
          }
        ],
        "passengers":[
          {
            "first_name": "KONSTANTIN",
            "last_name": "IVANOV"
          },
          {
            "first_name": "JULIA",
            "last_name": "IVANOVA"
          }
        ]
      }
    }
  }
}

Request example with auto_pay: true

{
  "checkout": {
    "test": true,
    "transaction_type": "payment",
    "attempts": 3,    
    "iframe": true,
    "settings": {
      "return_url": "https://return-url",
      "auto_pay": true,
      "language": "en"
    },
    "payment_method": {
      "types": [
        "credit_card"
      ],
      "credit_card": {
        "token": "13dded21-ed69-4590-8bcb-db522a89735c"
      }
    },
    "order": {
      "currency": "USD",
      "amount": 700,
      "description": "auto payment"
    },
    "customer": {
      "first_name": "John",
      "last_name": "Doe"
    }
  }
}

Response

In the transaction section response parameters replicate request parameters except the additional one:

checkout object token required string A payment token. redirect_url required string An URL of the payment widget where the customer can pay for the order related with the issued payment token.

Response example

{
  "checkout":
  {
    "token": "3241e439f8c87d941d92621a4bdc030d4c9a69c67f3b0cfe12de4a13cc34aa51",
    "redirect_url": "https://checkout.overpay.io/v2/checkout?token=3241e439f8c87d941d92621a4bdc030d4c9a69c67f3b0cfe12de4a13cc34aa51"
  }
}

Error response example

{
    "errors": {
        "checkout": {
            "settings": {
                "fail_url": [
                    "is in invalid format"
                ]
            },
            "payment_method": {
                "types": [
                    "must be an array"
                ]
            }
        }
    },
    "message": "fail_url is in invalid format, types must be an array"
}