Create a Charge

Does not apply if you selected Immediate Capture mode during Merchant registration.

The API call you will make to complete a Twisto payment is a call to our /charges endpoint.

This request is made once you have received an Approved checkout result back from Twisto.

Checkout status is communicated via webhooks, parameter in redirect URL back to your Merchant or can be retrieved in GET checkoutRetrieve request.

If checkout is not approved, /charges will be rejected

This API call will contain:

Authority
Reference (optional)
Amount
Currency
Capture flag

The Twisto API response will contain:

Charge Id - a unique reference for your charge, to be used for refunds or cancel / capture flows
State - the current state of the charge (authorized captured cancelled refunded error)
Captured amount
Refunded amount
Receipt number - a unique customer facing reference for your charge. To be printed on receipts.

State validation

If you are validating the value of the state in the response please ensure your system accepts the values listed above as successful responses.

This /charges API call should be made from your server and not directly from the client front end.

sequenceDiagram actor Customer participant Client Server->>Twisto: POST /charges using ID Twisto->>Server: Return Charge with status 'captured'

Authority

Twisto requires an authority token to process a charge. This will be:

The checkout Id obtained from the first API call to Twisto

Here is an example of how this information can be passed:

"authority": {
    "type": "checkout_id",
    "value": "string"
}

Charge details

Twisto requires certain charge details to be passed at the time of charge as below:

Reference (optional) - in case of Manual settlement will be visible in the bank transaction. If not specified, we will generate a random one
Amount
Currency
Capture flag

Here are some examples of how this information can be passed:

{
  "reference": "your_order_ reference",
  "amount": 300,
  "currency": "EUR"
}

Capture flag

When a charge is made, it must be specified if the funds should be immediately captured or only authorized (see Registering Merchant). This can be passed to Twisto as below:

{
  "capture": true
}

The full request

An example payload can be found below:

{
  "authority": {
    "type": "checkout_id",
    "value": "string"
  },
  "reference": "your_order_reference",
  "amount": 300,
  "currency": "EUR",
  "capture": true
}

Edge cases

No response due to network error

Not receiving a response makes it impossible to call ChargeRetrieve as you do not know the ID or if the request was successful.

There are 2 ways to work around that:

Send idempotency header on ChargeCreate request as specified in transactional API calls.
Call ChargeList (see API Reference | ChargeList) and from response match the charge by the reference.
- You either send a unique reference string on CheckoutCreate or the order is assigned a random one that you receive in the CheckoutCreate response.
- Note that ChargeList also allows filtering by datetime and pagination for easier filtering

With a successful response from Twisto, you have now completed your charge!