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 as4111111111111111will result in a failed charge - Cards ending with
4242, such as4242424242424242will result in a successful charge and a failed refund - Cards ending with 1881, such as
4012888888881881will 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 | |
|---|---|
| id | string (UUID) The unique identifier for the charge |
| store_id | string (UUID) The unique identifier for the store the charge was made to. |
| transaction_token_id | string (UUID) The unique identifier for the transaction token used to process the charge |
| transaction_token_type | string The transaction token type of transaction_token_id. |
| subscription_id | string (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_id | string The transaction identifier that was set during charge creation to be sent to the actual payments provider as the main identifier. |
| requested_amount | number The amount that was requested to be charged. |
| requested_currency | string (ISO-4217) The currency that was requested to be charged |
| requested_amount_formatted | string The amount that was requested to be charged formatted to include a decimal place if there is a minor currency unit. |
| charged_amount | number The amount that was charged. This may differ from the requested amount according to currency conversions |
| charged_currency | string (ISO-4217) The currency the charge was made in. This may differ from the requested currency according to currency conversions |
| charged_amount_formatted | string The amount that was charged formatted to include a decimal place if there is a minor currency unit. |
| only_direct_currency | boolean If this should use only gateway that support the requested currency. |
| capture_at | string (ISO-8601) The time this is automatically captured. |
| descriptor | string The descriptor used on a card statement. |
| status | string 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.code | string The error code of why a charge failed or errored. |
| error.message | string A short description of why a a charge failed |
| error.detail | string Additional details of why a charge failed |
| metadata | json Any metadata to associate with the charge. Any metadata made on a subscription will be passed to a charge associated with it. |
| mode | stringlive or test mode. Depends on the mode of the transaction token. |
| created_on | string (ISO-8601) The date the charge was created on. |
| redirect.redirect_id | string (UUID) The unique identifier for the redirect request. |
| redirect.endpoint | string (URL) The URL to redirect to after the payment is completed. |