Last updated
These docs are intended for a developer audience.Dismiss

Transactions

This topic describes the transaction resource. All payment transactions have a type, result, and status value. For information on how to inspect a payment transaction, see View payment transaction details.

Type

The type value defines the type of transaction.

Type Description
authorizeConfirms that the payment instrument is valid, that the customer is associated with the payment instrument, and that the funds are available. For payment cards, this transaction places a hold on the customer's account for the authorized amount. An authorized transaction is valid for seven days and can be captured or voided.
saleCombines the authorization and capture process in one transaction. A sale can be voided prior to settlement, and can be refunded after.
voidReverses an authorization, capture, or sale transaction. A void can only occur before settlement, otherwise a refund must be used to credit the customer.
refundReturns funds that had been collected from a customer's account. A refund is similar to a void, except a void must happen before the settlement of funds. On some occasions, a refund transaction can be voided.
creditPermits payments to a customer's account that exceed a just refund. A credit is a special and rare type of transaction. It requires special permissions from your acquiring bank.
setupCreates a payment instrument that can be used for future payments. The setup transaction performs actions from the setup instruction settings on the gateway account.
These actions are:
  • do nothing: A setup transaction is created and automatically marked as approved. The payment instrument is created and no further validation takes place.
  • authorize: Creates a setup transaction with an associated authorization child transaction. The result of the setup transaction matches the result of the authorization transaction. The authorization amount is equal to the setup transaction amount. For example, if 0 is sent as the amount, a 0 authorization is executed.
  • authorize and void: Creates a setup transaction with an associated authorization child transaction. The result of the setup transaction matches the result of the authorization transaction. If approved, the authorization transaction is immediately voided. If the setup transaction amount is $0, a $1 authorization is created; otherwise, the setup transaction amount is used.
  • Strong Customer Authentication (SCA): Creates two transactions, a setup transaction and a 3ds-authentication child transaction, which validates the cardholder by instructing them to authenticate their card through their issuing bank. This process is called 3D Secure (3DS) and may require the cardholder's interaction. For more information, see 3D Secure.

View transaction details

This process describes how to view transaction details. Select one of the following options:

View transaction details in the Rebilly UI
  1. In the left navigation bar, press Data tables, then press Payments.

  2. Select a segment, then in the top right of the table, press Filters .

  3. Press Add filter.

  4. In the Filter dropdown, select Type.

  5. In the Operation dropdown, select is in.

  6. In the Value field, select one or more of the following transaction types:

    • authorize
    • sale
    • void
    • refund
    • credit
    • 3ds-authentication
    • setup
    View declined setup transactions

    To view detailed information, such as logs, on declined setup transactions:

    1. In the right on the screen, in the Related transactions section, press the Child transaction.
    2. View detailed transaction information, interact with the Transaction details, Timeline, Webhook logs, and API logs.
  7. Press Apply filter.

  8. In the table, in the ID column, press a transaction.

View transaction details in the Rebilly API

Using the Retrieve transactions operation, in the type field, enter one of more of the following values separated by the ; character:

  • authorize
  • sale
  • void
  • refund
  • credit
  • 3ds-authentication
  • setup

Example: type=setup;3ds-authentication.

Result

The result value defines the result of completed transactions.

Result DescriptionWhen your application receives this result:
approvedA valid transaction is accepted by the issuing bank.Present the customer with a 'thank you' page which displays the billing descriptor.
declinedA payment transaction is not approved by the issuing bank. A reason code is supplied, which describes why the transaction is declined, such as: insufficient funds, incorrect billing address or CVV, and so on.Present the customer with a message stating that the transaction is declined. Ask your customer to retry the transaction with a different payment method. If you detect abuse, block the customer. For more information, see Blocklists.
abandonedA customer began payment but did not complete it within the Time To Live (TTL) window.Trigger an abandoned cart outreach campaign.
canceledTransaction is canceled by the merchant, or by an automation, such as a blocklist match before funds are removed from their account.Present the customer with an option to select a different payment method.
unknownA transaction is in process, the status changes as it is processed.Check if the status is waiting-approval. If it is, within the response, in the _links object, locate the approvalUrl and direct the customer to it.

To inspect a payment transaction using the UI, see View payment transaction details.

Status

The status value defines the execution status of a payment transaction.

Status Description
pendingTransaction is created and is queued.
sendingRequest is sent to a payment gateway.
completedTransaction is completed.
voidedTransaction authorization, capture, or sale transaction is reversed.
partially-refundedTransaction amount is partially refunded.
refundedTransaction amount is fully refunded.
disputedTransaction, or transaction amount, is disputed by the merchant or customer.

Successful payment transaction flow

The following is a successful payment transaction status flow.

Pending
Sending
Completed

Error and additional processing status

If a transaction does not receive a response from the payment gateway, or if there is a long delay in the response, one of the following statuses is returned.

Status Description
timeoutTransaction is not completed within the payment gateway account timeout period. For more information, see Set up a payment gateway - configure gateway account timeout.
conn-errorTransaction is not completed due to a connectivity issue.
never-sentThe request is not sent.
waiting-captureTransaction is approved with an authorization. The funds will be captured at some point in the future.
waiting-approvalThe transaction requires further action from the customer before it is marked as completed.
waiting-gatewayAwaiting an approval notification from the payment gateway before the transaction is marked as completed.
offsiteTransaction initiated. The customer has been redirected to a third-party website to complete the transaction.

Offsite and instant transactions

  • Offsite transactions: Customers must interact with a third-party website to complete a transaction. This interaction may be required as part of payment regulation.
  • Instant transactions: No customer interaction is required to complete a transaction.

Prevent duplicate transactions

To prevent a duplicate transaction, generate a unique ID that and pass it to the client form. Include the ID as the requestId property value in your transaction request. Only regenerate a different ID for the client form after you receive a completed status in the response from Rebilly.

Payment gateway response codes and messages

The payment gateway response contains a response code and message which describe the transaction. For example, if a transaction is declined, the message may contain information about why the transaction was declined. For information on how to view payment gateway response codes and messages, see View payment transaction details.

In Rebilly, the code and message received from the payment gateway is displayed in the 'Original message' and 'Original code' fields.

Rebilly uses a superset of the ISO 8583 — international standard for financial transaction card originated interchange messaging. Gateway codes are mapped to ISO 8583 as part of the gateway integration process. The standardized codes are displayed in the 'Message' and 'Code' fields. This standardized coding enables you to use the same response codes and messages across all payment gateway integrations.