Payment Tokens

Payment tokens allow merchants to process subsequent payments without requiring the customer to provide their payment details again.

A payment token is generated from an initial payment when the merchant requests token generation. The token securely references the customer's payment details and can then be used for subsequent payment operations.

Revup supports two types of token payments:

• Customer-Initiated — a single payment performed by the customer using a previously generated token.
• Merchant-Initiated (or Recurrences) — payments initiated by the merchant using a previously generated token, such as recurring or subscription payments.

Initial payment

The token is generated during an initial payment where the customer's payment details are present.

To request token generation, the merchant must set the generateToken field in the Order to true.

{
  "generateToken": true
}

The initial payment is processed using the customer's payment details. When the payment is successfully processed, Revup returns the generated token ID in the callback to the redirectUrl.

The token can then be stored by the merchant and used for subsequent payments.

Important: generateToken must be set to false for non-initial consumer_initiated payments and for non-initial recurrence payments.

Payment details

The paymentDetails object defines how the payment is going to be performed.

The paymentDetails.type field supports the following values:

Value	Description
consumer_initiated	The Order is created by the consumer and the payment is performed using a token.
recurrence	The Order is created by the merchant and the payment is performed using a token.
credit_card_present	The Order is created by the consumer and the payment is performed using card details.

For token payments, paymentDetails.type must therefore indicate whether the payment is Customer-Initiated or Merchant-Initiated.

For recurring payments, paymentDetails.sequence can also be used to indicate whether the payment is the initial, recurring, or final payment in the recurrence.

Customer-Initiated payments

A Customer-Initiated payment is a single payment performed by the customer using a previously generated payment token.

For this type of payment, the Order must indicate:

{
  "paymentDetails": {
    "type": "consumer_initiated"
  }
}

The payment uses the token generated during a previous payment instead of requiring the customer to provide their card details again.

The parentTransactionId identifies the transaction from which the payment is derived when required by the payment flow.

Merchant-Initiated payments

Merchant-Initiated payments, also referred to as recurrences, are payments initiated by the merchant using a previously generated payment token.

They can be used for recurring payments such as subscriptions.

For these payments, the Order must indicate:

{
  "paymentDetails": {
    "type": "recurrence"
  }
}

The merchant is responsible for determining when a subsequent payment should be made and for creating the corresponding Order.

Revup does not automatically manage the recurring schedule. The merchant must periodically request Revup to process a new transaction according to the service being charged.

Initial recurrence

The first payment in a recurring payment flow is different from subsequent recurring payments.

The customer is present for the initial payment and provides their payment details. The merchant creates an Order indicating that the payment is the initial payment and requests token generation.

For example:

{
  "generateToken": true,
  "paymentDetails": {
    "type": "recurrence",
    "sequence": "initial"
  }
}

The payment is then processed using the customer's payment details.

If the payment is successful, Revup generates a payment token and returns the token ID to the merchant.

The merchant must store the token ID and the transaction ID of this initial recurrence. The transaction ID is required as the parentTransactionId for subsequent recurring payments.

Subsequent recurring payments

Once the initial recurrence has been successfully processed, the merchant can use the generated token for subsequent payments.

For each subsequent recurrence, the merchant must create a new Order containing the information for that payment.

The Order must indicate that it is a recurring payment:

{
  "paymentDetails": {
    "type": "recurrence",
    "sequence": "recurring"
  },
  "parentTransactionId": "INITIAL_TRANSACTION_ID"
}

The parentTransactionId must reference the successful initial recurrence.

The payment itself is then performed using the token generated during the initial recurrence.

Performing a payment with a token

When a merchant performs a recurring payment directly through the Revup API, the payment is made using:

POST /orders/{orderId}/pay

The orderId of the Order created for the payment is provided as a path parameter.

The request body must contain the token ID in data and set paymentMethod to credit_card_token:

{
  "data": "TOKEN_ID",
  "paymentMethod": "credit_card_token"
}

For recurring payments, paymentMethod must always be set to credit_card_token.

The response contains the resulting transactionId and transactionStatus. A successful HTTP 200 response only means that Revup processed the request and forwarded it to the payment provider; it does not necessarily mean that the payment itself was successful.

The final result must be determined from the transaction status.

Final recurrence

A recurring payment sequence can be ended by creating a final recurrence.

The Order must indicate that the payment is the final payment in the sequence:

{
  "paymentDetails": {
    "type": "recurrence",
    "sequence": "final"
  },
  "parentTransactionId": "INITIAL_TRANSACTION_ID"
}

Once an initial recurrence is associated with a final recurrence, the payment token is disabled.

Token lifecycle

The token lifecycle can be summarized as follows:

The merchant is responsible for keeping the token ID and using it when subsequent payments need to be processed.

Important fields

The following Order fields are particularly relevant when working with payment tokens:

Field	Purpose
generateToken	Requests generation of a payment token during the initial payment.
paymentDetails.type	Indicates whether the payment is consumer_initiated, recurrence, or credit_card_present.
paymentDetails.sequence	Indicates whether a recurrence is initial, recurring, or final.
parentTransactionId	References the transaction associated with the initial recurrence for subsequent recurring payments.
orderId	Identifies the Order used for the payment.
money.amount	Specifies the amount to be charged.
money.currency	Specifies the currency of the payment.

For the complete list of Order fields, including their data types, request/response availability, and allowed values, see the Order fields reference.

Token payments and transaction status

A token payment creates a Transaction in the same way as other payment operations.

The resulting Transaction has its own transactionId and transactionStatus.

Depending on the payment flow, the initial response can indicate:

• success — the payment was successfully processed.
• failed — the payment failed.
• in_process — the payment is still being processed.
• waiting_user_interaction — additional user interaction, such as a 3DS challenge, is required.

The merchant must not assume that an HTTP 200 response means that the payment was successful. The transaction status must be checked to determine the result.

Summary

Payment tokens allow merchants to reuse previously provided payment information for subsequent payment operations.

The main flow is:

1. The customer provides their payment details during the initial payment.
2. The merchant sets generateToken to true.
3. Revup processes the payment and generates a token.
4. The merchant stores the token ID and the transaction ID of the initial payment.
5. For a subsequent payment, the merchant creates a new Order with the appropriate paymentDetails.type.
6. For recurring payments, the merchant also provides the parentTransactionId of the initial recurrence.
7. The merchant sends the token ID to the Payment endpoint using paymentMethod: "credit_card_token".
8. Revup creates a new Transaction and returns its status.
9. When a final recurrence is processed, the token is disabled.

For the complete API details, see the Payment API reference, Order fields, and Token-based payments documentation.