POST https://gate.reviopay.com/api/v1/purchases/Description
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// 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 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-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.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
due | object | no | 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. |
client | object | yes | Either this or .client_id is required. |
issued | object | no | 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. |
status | PurchaseStatus | no | Purchase status. Can have the following values: created: Purchase was created using POST /purchases/ or Billing API capabilities. One of: created, sent, viewed, error, cancelled, overdue, expired, hold, released, pending_release, pending_capture, preauthorized, paid, pending_execute, pending_charge, chargeback, pending_refund, refunded |
is_test | boolean | no | Indicates this is a test object, created using test API keys or using Billing section of UI while in test mode. |
payment | object | no | |
product | string | no | Defines which gateway product was used to create this Purchase. One of: purchases, billing_invoices, billing_subscriptions, billing_subscriptions_invoice |
user_id | string (uuid) | no | ID of user who has created this object in the Billing UI, if applicable. |
brand_id | string (uuid) | yes | 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?”. |
order_id | string | no | ID of corresponding order. |
platform | string | no | Platform this Purchase was created on. One of: web, api, ios, android, macos, windows |
purchase | PurchaseDetails | yes | Core information about the Purchase, including the products, total, currency and invoice fields. |
client_id | string (uuid) | no | 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). |
reference | string | no | Invoice reference. |
viewed_on | object | no | Time the payment form or invoice page was first viewed on |
company_id | string (uuid) | no | |
invoice_url | object | no | URL you will be able to access invoice for this Purchase at, if applicable |
checkout_url | object | no | URL you will be able to access the checkout for this Purchase at, if payment for it is possible. When building integrations, redirect the customer to this URL once purchase is created. |
send_receipt | boolean | no | Whether to send receipt email for this Purchase when it’s paid. |
skip_capture | boolean | no | 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. |
creator_agent | string | no | Identification of software (e.g. an ecommerce module and version) used to create this purchase, if any. |
referral_code | string | no | Referral code used with purchase. |
issuer_details | object | no | |
marked_as_paid | boolean | no | True if a purchase was manually marked as paid. |
status_history | object[] | no | History of status changes, latest last. Might contain entry about a related object, e.g. status change to refunded will contain a reference to the refund Payment. |
cancel_redirect | object | no | 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: <>'" . |
created_from_ip | string (IP) | no | IP the Purchase was created from. |
direct_post_url | object | no | URL that can be used for Direct Post integration. This functionality is activated for each merchant account individually. Please consult with your account manager if you wish to use it. |
force_recurring | boolean | no | 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. |
recurring_token | string (uuid) | no | ID of a recurring token (Purchase having is_recurring_token == true) that was used to pay this Purchase, if any. |
failure_redirect | object | no | If there’s a payment failure for this Purchase, your customer will be taken to this link. Otherwise a standard screen will be displayed. |
success_callback | object | no | When Purchase is paid for successfully, the success_callback URL will receive a POST request with the Purchase object’s data in body. |
success_redirect | object | no | When Purchase is paid for successfully, your customer will be taken to this link. Otherwise a standard screen will be displayed. |
transaction_data | object | no | Payment method-specific, read-only transaction data. Will contain information about all the transaction attempts and possible errors, if available. |
upsell_campaigns | string (uuid)[] | no | Array of IDs of related Upsell campaigns. |
refundable_amount | object | no | |
is_recurring_token | boolean | no | Indicates whether a recurring token (e.g. for card payments - card token) was saved for this Purchase. |
billing_template_id | string (uuid) | no | ID of a BillingTemplate that has spawned this Purchase, if any. |
currency_conversion | object | no | This object is present when automatic currency conversion has occurred upon creation of the purchase. Purchase’s original currency was changed and its original amount was converted using the exchange rate shown here. |
reference_generated | string | no | If you don’t provide an invoice reference yourself, this autogenerated value will be used as a reference instead. |
refund_availability | string | no | Specifies, if the purchase can be refunded fully and partially, only fully, partially or not at all. One of: all, full_only, partial_only, pis_all, pis_partial, none |
referral_campaign_id | string (uuid) | no | ID of Referral campaign. |
retain_level_details | object | no | Retain level detailed information for purchase. |
referral_code_details | object | no | Referral code detailed information for purchase. |
referral_code_generated | string | no | Referral code created by purchase. |
payment_method_whitelist | string[] | no | 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. |
id | string (uuid) | no | |
type | string | no | Object type identifier |
created_on | object | no | Object creation time |
updated_on | object | no | Object last modification time |
Example
curl -X POST https://gate.reviopay.com/api/v1/purchases/ \
-H 'Authorization: Bearer <YOUR_API_KEY>' \
-H 'Content-Type: application/json' \
-d '{
"client": {
"email": "test@test.com"
},
"brand_id": "409eb80e-3782-4b1d-afa8-b779759266a5",
"purchase": {
"products": [
{
"name": "test",
"price": 100
}
]
}
}'Responses
| Status | Description |
|---|---|
201 | OK |
400 | Invalid data submitted or request processing error |