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

Notice about specification changes
From the 16th of January 2023, the specifications will change as follows; when performing CVV authentication, a request for a provisional sale of one yen was sent, which was then canceled, but this will no longer be canceled and only authorization will be performed. The status after processing will be authorized.
If you were checking the CVV authorization result through Cancel, please update your configuration. We recommend using a “Token created” webhook or Transaction token:GET to check the result.

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
id	UUID The unique identifier for the transaction token.
store_id	UUID The unique identifier for the store the transaction token is associated with.
email	string The email of the customer that the payment data is for.
ip_address	string The IPv4 address of the customer’s device.
type	string The type of charge the token can be used for. One of `one_time`, `subscription`, or `recurring`.
usage_limit	string 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.
mode	string 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_type	string The type of payment method this token will hold.
metadata	object See metadata.
created_on	string (ISO-8601) The time that the transaction token was created on.
last_used_on	string (ISO-8601) The time that this token was last used.
data.card.cardholder	string The name of the card holder.
data.card.exp_month	number The month the card expires in.
data.card.exp_year	number The year the card expires in.
data.card.last_four	string The last for digits of the credit card.
data.card.brand	string The brand of the card. One of `visa`, `mastercard`, `jcb`, `diners_club`, `unionpay`, `american_express`, `maestro`, `discover`, or `unknown`.
data.card.category	string The category of the card. Not available for Apple Pay.
data.card.issuer	string The card issuer. Not available for Apple Pay.
data.card.sub_brand	string The sub brand of the card. Not available for Apple Pay.
data.billing.line1	string or null Line 1 of the billing address for the card
data.billing.line2	string or null Line 2 of the billing address for the card
data.billing.state	string or null The state/province/prefecture of the billing address for the card
data.billing.city	string or null The city the billing address for the card
data.billing.country	string (ISO Alpha-2) The country of the billing address of the card
data.billing.zip	string or null The zipcode of the billing address of the card
data.billing.phone_number.country_code	string or null The country code for the billing address phone number
data.billing.phone_number.local_number	string The local number for the billing address phone number
data.cvv_authorize.enabled	boolean Whether CVV authorization is enabled or not.
data.cvv_authorize.status	string The status of the authorization. One of `pending`, `current`, `failed`, or `inactive`.
data.cvv_authorize.currency	string (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_id	string (UUID) The charge ID of the charge used to make the authorization.
data.cvv_authorize.credentials_id	string (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.gateway	string The gateway that processed the payment. Available only for QR code payment.
data.brand	string The brand. Available only for online and bank transfer payment.
data.call_method	string The call method to generate the issuer token for, as requested by the client.
data.user_identifier	string The user identifier provided by the client, used to identify a unique user by the payment gateway.
data.os_type	string The operating system of the mobile device provided by the client.
data.customer_name	string The customer name. Available only for convenience store payment.
data.phone_number.country_code	string or null The country code for the billing address phone number
data.phone_number.local_number	string The local number for the billing address phone number
data.convenience_store	string The convenience store the payment will be made at. Available only for convenience store payment.
data.expiration_period	string (ISO-8601 Duration) The expiration period for this payment. Available only for convenience store payment.
data.expiration_time_shift	string (ISO-8601 Time with Timezone) The time to set for the payment after taking into account the `expiration_period` for this payment. Available only for convenience store payment.
data.match_amount	string The algorithm for matching on the transferred amount. Available only for bank transfer payment.
data.bank_code	string The bank code to make the payment to. Available only for bank transfer payment.
data.bank_name	string The bank name to make the payment to. Available only for bank transfer payment.
data.branch_code	string The branch code to make the payment to. Available only for bank transfer payment.
data.branch_name	string The branch name to make the payment to. Available only for bank transfer payment.
data.account_number	string The account number to make the payment to. Available only for bank transfer payment.
data.account_holder_name	string The name of the account holder to make the payment to. Available only for bank transfer payment.