Charges

After creating a transaction token, a charge can be created to complete a payment.

Charges are processed asynchronously, so on creation they will in a pending state. After has finished processing the payment, the status will be automatically changed to successful, failed, or error depending on the result. To be notified of the final state of a charge, you can register a webhook for the CHARGE_FINISHED event. Alternatively, a long poll can be made when getting a charge resource but does not guaranty it would have entered the final state.

Authorization

The authorization is used to confirm that the credit card is available actually and to reserve credit facility. Next create a capture to determine the payment.

To authorize, set capture parameter as false when creating a charge. You can also use capture_at parameter if you want to capture the charge automatically in specific date time. The created charge will in a pending state. After the card issuer has authorized the request, the status will be automatically change to authorized. Authorization may be in a failed state for various reasons, such as card has expired or insufficient credit faiility, etc.

To capture a charge, make a request for the authorized charge. Please refer to create a capture for charge.

When you don’t capture the charge, credit facility should be released by creating cancel.

Test card numbers

When using a test mode application token to make a charge, use the following card numbers to change the outcome of the charge:

  • Cards ending with 1111, such as 4111111111111111 will result in a failed charge
  • Cards ending with 4242, such as 4242424242424242 will result in a successful charge and a failed refund
  • Cards ending with 1881, such as 4012888888881881 will result in a successful charge and a failed cancel
  • All other valid cards numbers will result in a successful charge and refund. You can generate some random test card numbers using this site.

The charge object

Fields
idstring (UUID)
The unique identifier for the charge
store_idstring (UUID)
The unique identifier for the store the charge was made to.
transaction_token_idstring (UUID)
The unique identifier for the transaction token used to process the charge
transaction_token_typestring
The transaction token type of transaction_token_id.
subscription_idstring (UUID)
The unique identifier for the subscription this charge was created for. It will be absent if the charge was not linked to a subscription.
merchant_transaction_idstring
The transaction identifier that was set during charge creation to be sent to the actual payments provider as the main identifier.
requested_amountnumber
The amount that was requested to be charged.
requested_currencystring (ISO-4217)
The currency that was requested to be charged
requested_amount_formattedstring
The amount that was requested to be
charged formatted to include a decimal place if there is a minor currency unit.
charged_amountnumber
The amount that was charged. This may differ from the
requested amount according to currency conversions
charged_currencystring (ISO-4217)
The currency the charge was made in. This may
differ from the requested currency according to currency conversions
charged_amount_formattedstring
The amount that was charged formatted
to include a decimal place if there is a minor currency unit.
only_direct_currencyboolean
If this should use only gateway that support the requested currency.
capture_atstring (ISO-8601)
The time this is automatically captured.
descriptorstring
The descriptor used on a card statement.
statusstring
The status of the charge. One of pending, awaiting, successful, failed, error, authorized or canceled. In the event of an error status, this means abnormal state and the status may change after the support team has reviewed the charge
error.codestring
The error code of why a charge failed or errored.
error.messagestring
A short description of why a a charge failed
error.detailstring
Additional details of why a charge failed
metadatajson
Any metadata to associate with the charge. Any metadata made on a subscription will be passed to a charge associated with it.
modestring
live or test mode. Depends on the mode of the transaction token.
created_onstring (ISO-8601)
The date the charge was created on.