Create a purchase – the main request for any e-commerce integration.

post

https://gate.reviopay.com/api/v1/purchases/

To run payments in your application use POST /purchases/, request to register payments and receive the checkout link (checkout_url). After the payment is processed, gateway will redirect the client back to your website (take note of success_redirect, failure_redirect).

You have three options to check payment status: 1) use success_callback parameter of Purchase object; 2) use GET /purchases/<purchase_id>/ request; 3) set up a Webhook using the UI or Webhook API to listen to purchase.paid or purchase.payment_failure event on your server.

Using skip_capture flag allows you to separate the authentication and payment execution steps, allowing you to reserve funds on payer’s card account for some time. This flag can also enable preauthorization capability, allowing you to save the card without a financial transaction, if available.

In case making a purchase client agrees to store his card for the upcoming purchases, next time he will be able to pay in a single click.

Instead of a redirect you can also utilize Direct Post checkout: you can create an HTML <form> on your website with method="POST" and action pointing to direct_post_url of a created Purchase. You will also need to saturate form with <input>-s for card data fields. As a result, when a payer submits their card data, it will be posted straight to our system, allowing you to customize the checkout as you wish while your PCI DSS requirement is only raised to SAQ A-EP, as your system doesn't receive or process card data. For more details, see the documentation on Purchase's direct_post_url field.

To pay for test Purchases, use 4444 3333 2222 1111 as the card number, 123 as CVC, any date/month greater than now as expiry and any (Latin) cardholder name. Any other card number/CVC/expiry not greater or equal than the current month will all fail a test payment.

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

Record of a single purchase operation, either a transaction originating from e-commerce integration or invoice sent. Has a status attribute, e.g. can be created, paid or refunded.

client

object

required

Contains details about the client of a purchase or payment - the remote payer/fund recipient party.

purchase

object

required

Core information about the Purchase, including the products, total, currency and invoice fields. If you're using invoicing via /billing/ or /billing_templates/, this object will be copied 1:1 from BillingTemplate you specify to the resulting Purchases (also to subscription Purchases).

brand_id

uuid

required

ID of the brand to create this Purchase for. You can copy it down in the API section, see the "specify the ID of the Brand" link in answer to "How to setup payments on website or in mobile app?".

client_id

uuid | null

Defaults to null

ID of a Client object used to initialize ClientDetails (.client) of this Purchase. Either this field or specifying .client object is required (you can only specify a value for one of these fields). All ClientDetails fields from the Client will be copied to .client object. Note that editing Client object won't change the respective fields in already created Purchases.

If you specify this field and your client saves a recurring_token (for instance, by saving their card), the respective ClientRecurringToken will be created. See the /clients/{id}/recurring_tokens/ endpoint.

send_receipt

boolean

Defaults to false

Whether to send receipt email for this Purchase when it's paid.

skip_capture

boolean

Defaults to false

Card payment-specific: if set to true, only authorize the payment (place funds on hold) when payer enters his card data and pays. This option requires a POST /capture/ or POST /release/ later on.

You can use the preauthorization feature if you set this parameter to true and make the Purchase with purchase.total == 0 (this can be achieved by providing a list of purchase.products with a total price of 0, or simply overriding the total using purchase.total_override to 0). The resulting Purchase can only be "paid" by the client (only cardholder data verification will happen, without a financial transaction) by card and will enforce saving the client's card. When this happens, the Purchase will have status of preauthorized and the purchase.preauthorized webhook callbacks will be emitted.

Trying to use skip_capture (or preauthorization) without any payment methods that support the respective actions (this can be a result of payment_method_whitelist field being used) will result in an error on Purchase creation request step. Please check the GET /payment_methods/ response for your desired Purchase parameters and/or consult with your account manager.

force_recurring

boolean

Defaults to false

If the used payment method supports recurring payment functionality, forces the customer's payment credentials to be saved for possible later recurring payments, without giving the customer a choice in the matter.

reference

string

length ≤ 128

Invoice reference.

issued

string | null

Value for 'Invoice issued' field. Display-only, does not get validated. If not provided, will be generated as the current date in purchase.timezone at the moment of Purchase's creation.

due

integer | null

When the payment is due for this Purchase. The default behaviour is to still allow payment once this moment passes. To change that, set purchase.due_strict to true.

payment_method_whitelist

array of strings

length ≥ 1

An optional whitelist of payment methods availble for this purchase. Use this field if you want to restrict your payer to pay using only one or several specific methods.

Using this field and at the same time trying to use specific capabilities of a Purchase (e.g. skip_capture or charging it using a saved card token using POST /purchases/{id}/charge/) can cause a situation when there are no payment methods available for paying this Purchase. This will cause a validation error on Purchase creation. Please check the GET /payment_methods/ response for your desired Purchase parameters and/or consult with your account manager.

payment_method_whitelist

Payment method name as returned by GET /payment_methods/.

success_redirect

url

length ≤ 500

When Purchase is paid for successfully, your customer will be taken to this link. Otherwise a standard screen will be displayed.

failure_redirect

url

length ≤ 500

If there's a payment failure for this Purchase, your customer will be taken to this link. Otherwise a standard screen will be displayed.

cancel_redirect

url

length ≤ 500

If you provide this link, customer will have an option to go to it instead of making payment (a button with 'Return to seller' text will be displayed). Can't contain any of the following symbols: <>'" .

Be aware that this does not cancel the payment (e.g. does not do the equivalent of doing the POST /purchases/{id}/cancel/ request); the client will still be able to press 'Back' in the browser and perform the payment.

success_callback

url

length ≤ 500

When Purchase is paid for successfully, the success_callback URL will receive a POST request with the Purchase object's data in body.

creator_agent

string

length ≤ 32

Identification of software (e.g. an ecommerce module and version) used to create this purchase, if any.

platform

string

enum

Platform this Purchase was created on.

Allowed:

201OK

400Invalid data submitted or request processing error