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. |
| 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.three_ds.enabled | boolean Whether or not 3DS is enabled for this transaction token. Can only be true for recurring token type |
| data.three_ds.status | string The status of 3DS when enabled. One of pending, awaiting, successful, failed, or error. |
| data.three_ds.redirect_endpoint | string (URL) The endpoint to redirect to when the client returns from 3DS authentication. If not set, a default completion page will be displayed. |
| data.three_ds.redirect_id | string (UUID) The unique identifier for the redirect request. Will be populated if the redirect was successfully set. |
| 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. |