Charge a purchase using a saved token
Charge a purchase using a recurring_token
provided in the request body. Its value should be an id
of a Purchase that has is_recurring_token == true
. This purchase will be paid using the same method (e.g. same card) as the one used to pay the recurring_token
purchase.
If this operation takes too long to be processed on the acquirer side - you will get a response with status code 200 and a Purchase object having status
= pending_charge
in body (you will receive a corresponding Webhook callback too for a purchase.pending_charge
event). To be notified of a successful operation completion, please subscribe to purchase.paid
callback event - it will deliver an updated Purchase with status
= paid
. Alternatively, if charge fails, you will receive a purchase.payment_failure
callback event.
If recurring charge fails due to payment processing error, you will receive HTTP response code 400 with error code purchase_charge_error
. In this case, to get more details about the error, you should perform a GET /purchase/
request for the Purchase you tried to charge. In transaction_data.attempts[]
array (newest element first) you’ll find the corresponding attempt with error code and description in .error
parameter.
Authorizations
Bearer authentication header of the form Bearer <token>
, where <token>
is your auth token.
Path Parameters
Object ID (UUID)
Body
ID of a recurring token (Purchase having is_recurring_token == true
) to use.
Response
Object type identifier
Object creation time
Object last modification time
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).
Details of an executed transaction. Read-only for Purchase
s and Payout
s. 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 thePOST /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 ofpurchase.due_strict
having been set totrue
).blocked
: Likeerror
, 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 runPOST /capture/
orPOST /release/
for this payment to capture the payment or return funds to the client, respectively.released
: This Purchase previously hadhold
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 byPOST /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 byPOST /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 (orhold
in case ofskip_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 byPOST /purchases/{id}/charge/
operation when it takes longer than expected to process on the acquirer side.cleared
: Funds for this Purchase (that was alreadypaid
) 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 inpaid
status instead.settled
: Settlement was issued for funds for this Purchase (that was alreadypaid
). All non-card payment methods and some card payment methods (depends on configuration) don't use this status and Purchases paid using them stay inpaid
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 byPOST /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.
created
, sent
, viewed
, error
, cancelled
, overdue
, expired
, blocked
, hold
, released
, pending_release
, pending_capture
, preauthorized
, paid
, pending_execute
, pending_charge
, cleared
, settled
, chargeback
, pending_refund
, refunded
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 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 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.
all
, full_only
, partial_only
, pis_all
, pis_partial
, none
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.
web
, api
, ios
, android
, macos
, windows
Defines which gateway product was used to create this Purchase.
purchases
, billing_invoices
, billing_subscriptions
, billing_subscriptions_invoice
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.