Create a purchase

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Either this or .client_id is 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).

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?".

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.

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

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.

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.

Invoice reference.

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.

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.

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.

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

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

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.

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

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

Platform this Purchase was created on.

Either this or .client_id is 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).

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?".

Object type identifier

Object creation time

Object last modification time

Details of an executed transaction. Read-only for Purchases and Payouts. For an unpaid Purchase, this object will be null.

Read-only details of issuer company/brand, persisted for invoice display.

Payment method-specific, read-only transaction data. Will contain information about all the transaction attempts and possible errors, if available.

Purchase status. Can have the following values:

• created: Purchase was created using POST /purchases/ or Billing API capabilities.
• sent: Invoice for this purchase was sent over email using Billing API capabilities.
• viewed: The client has viewed the payform and/or invoice details for this purchase.
• error: There was a failed payment attempt for this purchase because of a problem with customer's payment instrument (e.g. low account balance). You can analyze the .transaction_data to get information on reason of the failure.
• cancelled: Purchase was cancelled using the POST /purchases/{id}/cancel/ endpoint; payment for it is not possible anymore.
• overdue: Purchase is past its' .due, but payment for it is still possible (unless e.g. POST /purchases/{id}/cancel/ is used).
• expired: Purchase is past its' .due and payment for it isn't possible anymore (as a result of purchase.due_strict having been set to true).
• blocked: Like error, but payment attempt was blocked due to fraud scoring below threshold or other security checks not passing.
• hold: Funds are on hold for this Purchase (.skip_capture: true was used). You can now run POST /capture/ or POST /release/ for this payment to capture the payment or return funds to the client, respectively.
• released: This Purchase previously had hold status, but funds have since been released and returned to the customer's card.
• pending_release: release of funds for this Purchase is in processing, but is not finalized on the acquirer side yet. Is set by POST /purchases/{id}/release/ operation when it takes longer than expected to process on the acquirer side.
• pending_capture: capture of funds for this Purchase is in processing, but is not finalized on the acquirer side yet. Is set by POST /purchases/{id}/capture/ operation when it takes longer than expected to process on the acquirer side.
• preauthorized: A preauthorization of a card (authorization of card data without a financial transaction) was executed successfully using this Purchase. See the description of the .skip_capture field for more details.
• paid: Purchase was successfully paid for.
• pending_execute: Payment (or hold in case of skip_capture) for this Purchase is in processing, but is not finalized on the acquirer side yet.
• pending_charge: Recurring payment for this Purchase is in processing, but is not finalized on the acquirer side yet. Is set by POST /purchases/{id}/charge/ operation when it takes longer than expected to process on the acquirer side.
• cleared: Funds for this Purchase (that was already paid) have been transferred for clearing in payment card network. All non-card payment methods and some card payment methods (depends on configuration) don't use this status and Purchases paid using them stay in paid status instead.
• settled: Settlement was issued for funds for this Purchase (that was already paid). All non-card payment methods and some card payment methods (depends on configuration) don't use this status and Purchases paid using them stay in paid status instead.
• chargeback: A chargeback was registered for this, previously paid, Purchase.
• pending_refund: a refund (full or partial) for this Purchase is in processing, but is not finalized on the acquirer side yet. Is set by POST /purchases/{id}/refund/ operation when it takes longer than expected to process on the acquirer side.
• refunded: This Purchase had its payment refunded, fully or partially.

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.

Time the payment form or invoice page was first viewed on

Indicates this is a test object, created using test API keys or using Billing section of UI while in test mode.

ID of user who has created this object in the Billing UI, if applicable.

ID of a BillingTemplate that has spawned this Purchase, if any.

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.

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

Indicates whether a recurring token (e.g. for card payments - card token) was saved for this Purchase. If this is true, the id of this Purchase can be used as a recurring_token in POST /purchases/{id}/charge/, enabling you to pay for that Purchase using the same method (same card for card payments) that this one was paid with.

ID of a recurring token (Purchase having is_recurring_token == true) that was used to pay this Purchase, if any.

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.

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.

If you don't provide an invoice reference yourself, this autogenerated value will be used as a reference instead.

Invoice reference.

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.

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.

Specifies, if the purchase can be refunded fully and partially, only fully, partially or not at all.

Amount of money as the smallest indivisible units of the currency. Examples: 1 cent for EUR and 1 Yen for JPY.

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.

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.

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

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

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.

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

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

Platform this Purchase was created on.

Defines which gateway product was used to create this Purchase.

IP the Purchase was created from.

URL you will be able to access invoice for this Purchase at, if applicable

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.

You can add the preferred query arg to the checkout_url in order to force redirect the client straight to the checkout for a specific payment method (?preferred={payment_method}, where {payment_method} is the payment method name as returned by GET /payment_methods/). If this method redirects the client further to a different system and no customer data entry is needed on gateway's checkout page, your payer will be taken straight to that page (not seeing the gateway's checkout UI); otherwise, he will see the payment method entry UI on the gateway checkout page.

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.

Will be null if payment for purchase is not possible, purchase.request_client_details isn't empty or success_redirect/failure_redirect are not provided - these all break the usual direct post flow.

To leverage Direct Post checkout, create a <form> having method="POST" action="<direct_post_url value>" and include the following inputs:

cardholder_name: text, Latin letters only (space and apostrophe ('), dot (.), dash (-) symbols are also allowed), max 30 chars

card_number: text, digits only, no whitespace, max 19 chars

expires: text in 'MM/YY' format, digits and a slash only /^\d{2}\/\d{2}$/, max 5 chars

cvc: numeric string of 3 or 4 digits

remember_card: checkbox with value="on" (the default when omitting value attribute of a checkbox input)

Ensure the validation as listed above! Validation errors will be treated as payment failures. Obviously, you can style this form to fit in with the rest of your website.

When your payer submits this form (don't forget a <button> or <input type="submit">), he will POST the data directly to the gateway system. There, with minimal interaction with gateway's interface, payment will be processed. In the process, your customer might get redirected to authenticate against 3D Secure system of his card issuer bank (this depends on settings of his card and your account). After that, payer will be taken to success_redirect or failure_redirect depending on the payment result (as in the usual payment flow).

Be aware, though, that while not having to process card data allows you not to comply with the entirety of PCI DSS SAQ D requirements, having sensitive cardholder data entry form on your website does raise your PCI DSS scope to SAQ A-EP. Contact your account manager to receive advisory and assistance for this integration method.

True if a purchase was manually marked as paid.

ID of corresponding order.