Transaction tokens

A transaction token is a resource used to collect payment data and personal information gathered about a customer. After creation, the transaction token is used to make a charge or subscription. If your service is not PCI compliant, you should avoid collecting sensitive information like card numbers and use one of our solutions such as our mobile widget for Android or iOS, browser widget, or payments terminal app.

Token types

Transaction tokens can be created as one of the following types:

  • one_time – For creating a charge resource. Default option.
  • subscription – For creating a subscription resource.
  • recurring – For creating a charge resource.

One time tokens

A one time token is a token that can be used to make a single charge and is valid for 5 minutes after its creation. It is possible to create multiple one time tokens concurrently to process high volume of charges, but there are limits on how many times a single card can be charged within a short timespan.

One time tokens can also be used to authorize a charge now, and captured (executed) at a later date in the future. This can be a fixed date that will be executed automatically, or at an arbitrary time triggered manually via an API call. The amount captured can be less than or equals to the authorized amount, but not more. Authorization charges also requires gateway credentials with that capability. See charges for more details.

Subscription tokens

When there is a need to charge a customer on a fixed schedule, it is recommended to use a subscription token. Such a token provides the ability to set the subscription charge interval, the initial charge amount and recurring amount and the start date of the subscription cycle. This token is valid for 5 minutes after its creation. A subscription will continue indefinetly until it is canceled.

Subscriptions also have the ability to create installment plans for repayment over a period of time. See the subscription resource for more details.

Recurring tokens

Recurring (reusable) transaction token can only be created if your account has been authorized to do so. Depending on the verification process, you may be able to create an infinitely usable token, which can be used freely to make charges at any time, or a bounded token with a usage limit, in which a token can only be used once in the given time period.

Once a token has been created, the personal information will be stored securely on our platform and cannot be modified. The only information that can be PATCH is the email, metadata and the CVV number. The latter is required when using a recurring token and the charge amount exceeds a predefined limit in the store configuration. This is to ensure that user consent to received for the additional charge above the defined limit.

Take note that if the token is not used within 5 minutes of the creation, the CVV is automatically expired and depending on your configuration, you might need to update the token with the CVV value again.

CVV Authorization

CVV authorization is a feature only available on recurring tokens for credit card payments that allow you to pre authorize a valid credit card along with its corresponding CVV so that a charge can be made at a later time. A valid use case of this would be to allow a customer to save their card information and then allow them to make a purchase with it at anytime after that. By default, this feature is not enabled unless.

data.cvv_authorize.enabled = true.

Internally, the system will make an authorization request to the payment provider and this may take at least a few seconds. Once this is completed, the recurring token will be locked into the payment provider that the information was authorized with and cvv_authorize.status will be updated to current. The token will not be able to make a charge until the authorization process has been completed successfully.

It is recommended to always ensure that the status is in a current state prior to making a charge. If it is otherwise, please update the CVV value before proceeding.

If for any reason the payment provider has been unlinked from the merchant, the token will transition to an inactive state, which will then require the CVV value to be updated on the token. Upon which the authorization will automatically be attempted.

Payment methods

In addition, transaction tokens also have the following payment methods:

  • card – Credit card payment.
  • qr_scan – Customer presented (CPM) QR code payment. One time token only.
  • qr_merchant – Merchant presented (MPM) QR code payment. One time token only.
  • online – Online payment. One time token only.
  • apple_pay – Apple pay payment.
  • konbini – Convenience store payment. Recurring token not allowed.
  • bank_transfer – Bank transfer payment.

Different payment methods will have different data requirements. See the data parameter for creating a transaction token.

The transaction token object

Fields
idUUID
The unique identifier for the transaction token.
store_idUUID
The unique identifier for the store the transaction token is associated with.
emailstring
The email of the customer that the payment data is for.
ip_addressstring
The IPv4 address of the customer’s device.
typestring
The type of charge the token can be used for. One of one_time, subscription, or recurring.
usage_limitstring
If the type of token is recurring, this determines frequently the token is usable.
One of daily, weekly, monthly, annually, or null if the recurring token has no usage limit.
modestring
Which mode the token was created. This is determined by the application token used to create the transaction token. Can be live or test.
payment_typestring
The type of payment method this token will hold.
metadataobject
See metadata.
created_onstring (ISO-8601)
The time that the transaction token was created on.
last_used_onstring (ISO-8601)
The time that this token was last used.
data.card.cardholderstring
The name of the card holder.
data.card.exp_monthnumber
The month the card expires in.
data.card.exp_yearnumber
The year the card expires in.
data.card.last_fourstring
The last for digits of the credit card.
data.card.brandstring
The brand of the card. One of visa, mastercard, jcb, diners_club, unionpay, american_express, maestro, discover, or unknown.
data.card.categorystring
The category of the card. Not available for Apple Pay.
data.card.issuerstring
The card issuer. Not available for Apple Pay.
data.card.sub_brandstring
The sub brand of the card. Not available for Apple Pay.
data.billing.line1string or null
Line 1 of the billing address for the card
data.billing.line2string or null
Line 2 of the billing address for the card
data.billing.statestring or null
The state/province/prefecture of the billing address for the card
data.billing.citystring or null
The city the billing address for the card
data.billing.countrystring (ISO Alpha-2)
The country of the billing address of the card
data.billing.zipstring or null
The zipcode of the billing address of the card
data.billing.phone_number.country_codestring or null
The country code for the billing address phone number
data.billing.phone_number.local_numberstring
The local number for the billing address phone number
data.cvv_authorize.enabledboolean
Whether CVV authorization is enabled or not.
data.cvv_authorize.statusstring
The status of the authorization. One of pending, current, failed, or inactive.
data.cvv_authorize.currencystring (ISO-4217)
The currency requested to make the authorization in, if manually overridden. Defaults to the base merchant currency if not present.
data.cvv_authorize.charge_idstring (UUID)
The charge ID of the charge used to make the authorization.
data.cvv_authorize.credentials_idstring (UUID)
The credentials ID that was used to make the authorization. The token is now locked to this credential and deactivating it will cause the token to change to an inactive state.
data.gatewaystring
The gateway that processed the payment. Available only for QR code payment.
data.brandstring
The brand.
Available only for online and bank transfer payment.
data.call_methodstring
The call method to generate the issuer token for, as requested by the client.
data.user_identifierstring
The user identifier provided by the client, used to identify a unique user by the payment gateway.
data.os_typestring
The operating system of the mobile device provided by the client.
data.customer_namestring
The customer name. Available only for convenience store payment.
data.phone_number.country_codestring or null
The country code for the billing address phone number
data.phone_number.local_numberstring
The local number for the billing address phone number
data.convenience_storestring
The convenience store the payment will be made at. Available only for convenience store payment.
data.expiration_datestring (ISO-8601)
The expiration date for this payment. Available only for convenience store payment.
data.match_amountstring
The algorithm for matching on the transferred amount. Available only for bank transfer payment.
data.bank_codestring
The bank code to make the payment to. Available only for bank transfer payment.
data.bank_namestring
The bank name to make the payment to. Available only for bank transfer payment.
data.branch_codestring
The branch code to make the payment to. Available only for bank transfer payment.
data.branch_namestring
The branch name to make the payment to. Available only for bank transfer payment.
data.account_numberstring
The account number to make the payment to. Available only for bank transfer payment.
data.account_holder_namestring
The name of the account holder to make the payment to. Available only for bank transfer payment.