Tokens

Paidy's token service provides a simple and secure way for re-charging consumers for goods and services, like membership fees, subscriptions, etc. In the same way that you can save a consumer's credit card details for charging them at a future date, you can save a token for charging a consumer at Paidy. The token is a link to the consumer's account at Paidy, and allows you to send new payment requests, without requiring the consumer to check out again.

The token service offers many benefits, including:

  • It enables you to sell subscription services to non-credit card users. Just like with Paidy payments, consumers do not have to enter credit card details.
  • The number one reason that a subscription gets rejected for a credit card payment is because the credit card has expired. Since Paidy tokens do not expire, this may reduce the failure rate for subscription payments.
  • When you create a token, the consumer is not charged anything. Token creation and payment creation are separate requests. This flexible implementation allows you to charge consumers immediately, wait until the goods are ready to ship, wait until after a "trial period", etc.
  • The amount is not set when the token is created. Every time you create a payment using this token, you specify the amount, which allows you to change the amount you charge a consumer from payment-to-payment.

The flexibility that is built into Paidy's token service allows you to tailor the token implementation to your customer's needs.

  How do tokens work at Paidy

[how-to diagram]

Token creation

Tokens are created by the consumer via Paidy Checkout. From the checkout page, a consumer selects Paidy as their method of payment and Paidy Checkout launches, authenticates the user, and creates the token. After you save the token ID to your backend, you can then use this token to create payments on behalf of that consumer.

In Paidy, a payment is not created when a token is issued. The token is simply a link to the consumer's Paidy account. Then, when you are ready to create a payment (using the token), you send a request via the Paidy API. Payment authorization is done when you create a payment using a token. This means that even though the token was authenticated successfully, when processed the payment might still be rejected due to Paidy's credit assessment.

Token management

Once a token is created, you can use the Paidy API to suspend, resume, or delete the token.

  • The suspend and delete requests both disable a token - the difference is "suspend" temporarily disables a token, whereas "delete" permanently disables a token.
  • The resume request reactivates a token that was disabled using "suspend", enabling it to be used for creating payments again. (You cannot resume a token that was disabled using "delete".)

Consumers can also suspend or resume tokens by calling Paidy Support. If a consumer suspends or resumes a token, you will receive a webhook notification (if you have webhooks configured) alerting you to the change.
A suspended token can only be resumed by the same authority that suspended it. In other words, if you suspend a token, a consumer cannot resume it, and vice versa.

Lifecycle of a token

[token lifecycle diagram]

  • STATE

    DESCRIPTION

  • ACTIVE

    This is the initial state for a token after it is created successfully. A suspended token that is resumed is also in the ACTIVE state. You can only create payments with tokens that are in the ACTIVE state.
    Valid API requests for a token in the ACTIVE state: create payment, suspend, delete, get one, get all

  • SUSPENDED

    A token is in this state after it was successfully suspended. Once suspended, a token cannot be used to create a payment.
    Valid API requests for a token in the SUSPENDED state: resume, delete, get one, get all

  • DELETED

    A token is in this state when you successfully delete it. Once deleted, a token cannot be used to create a payment and cannot be resumed.
    Since tokens never expire, the delete request should be used to disable tokens that are no longer needed.
    When a token is in the DELETED state, the only valid API request is: get one

  Tokens API

The Paidy API provides an easy and secure way to manage tokens. Using the API, you can:

  • Suspend a token: changes the status to SUSPENDED. Once suspended, a token cannot be used to create a payment.
  • Resume a token: changes the status to ACTIVE. Once the token is resumed, it can be used to create a payment again. You can only resume a token that you suspended.
  • Delete a token: changes the status to DELETED. Once a token is deleted, it cannot be used to create a payment and it cannot be resumed.
  • Retrieve a token: retrieves the requested token object.
  • Retrieve all tokens: retrieves all token objects (for all of your consumers) with a status of ACTIVE or SUSPENDED.

Secure communication

TLS is an industry standard protocol for encrypting network communications and providing end-to-end security over the Internet. The Paidy API supports TLS version 1.1 and higher. Additionally, we rely on HTTPS to ensure all data is transmitted securely.

  Creating a token

Tokens are issued via Paidy Checkout. The consumer enters their email address and mobile number in Paidy Checkout and Paidy authenticates the consumer via SMS. If successful, Paidy creates the new token. You can then save the token and use it to create future payments on behalf of the consumer.

Note, payment authorization is not done when a token is being created. Payment authorization is done when you process a payment using the token. This means that even though the token was authenticated successfully, when processed the payment might still be rejected due to Paidy's credit assessment.

A consumer can have multiple tokens - for the same merchant or for different merchants. And tokens do not expire. When a token is no longer required, send a delete request via the Paidy API.

  Suspending a token

To temporarily suspend a token, you send a request to the `/tokens/{id}/suspend` endpoint, where {id} is the Paidy token ID. If successful, the status of the token is updated to SUSPENDED and if you try to create a payment using that token, it will be rejected.

token suspend

You can use either the suspend request or the delete request to "disable" a token. The suspend request temporarily disables a token; the token can be resumed at a future date and used to create new payments again. Whereas, a token that has been deleted cannot be resumed and cannot be used to create payments again.

Example:


curl -X "POST" "https://api.paidy.com/tokens/tok_WK5KjCEAAA0RvPp9/suspend" \
  -H "Content-Type: application/json" \
  -H "Paidy-Version: 2018-04-10" \
  -H "Authorization: Bearer $secret_key" \
  -d $'{
	"reason": {
		"code": "fraud.suspected",
		"description": "Token suspended because fraud suspected."
	},
	"wallet_id": "default"
	}'

Each merchant will have different reasons for why they may want to suspend a token, depending on the products they sell, their business practices, and their customer service policies. The following are just a few examples of why a merchant may want to suspend a token:

  • If the consumer has called to question a charge that was made using this token, and you do not want any further payments created using this token until the consumer's query is resolved.
  • If the consumer has called to temporarily suspend a subscription (if they are going to be away for example).
  • If you are having issues with the consumer (for example their current bill is overdue) and you do not want new payments created using this token until their account is in order again.
  • If there is some suspicious activity using this token.

You must include the reason for the suspension in the request. For the reason code, use one of the values in the following table. If you send a code that is not listed here, the system will return an error. You can use the description field to give additional details around the reason for the suspension.

  • CODE

    USE

  • consumer.requested

    Send this code if the consumer has called you to request the token be suspended.

  • merchant.requested

    Send this code if you want to suspend the token.

  • fraud.suspected

    Send this code if there is suspicious activity using the token.

  • general

    Send this code in any other scenario.

Paidy verifies the token is ACTIVE and suspends the token. A suspended token will be marked with the datetime it was suspended and the authority, i.e., who requested the suspension. For tokens suspended via the API, Paidy sets the authority field to "merchant".

Tokens can be suspended by the merchant using the API or by the consumer by calling Paidy Support. When a token is suspended, either by you or by a consumer, you will receive a webhook notification (if you have webhooks configured) alerting you to the change.

  Resuming a token

To resume a suspended token, you send a POST request to the `/tokens/{id}/resume` endpoint, where {id} is the Paidy token ID. A token can be suspended by either the consumer or the merchant, and a suspended token can only be resumed by the same authority that suspended it. If the consumer suspended it and the merchant tries to resume it, the request will fail, and vice versa.

token resume

Example: 


curl -X "POST" "https://api.paidy.com/tokens/tok_WK5KjCEAAA0RvPp9/resume" \
  -H "Content-Type: application/json" \
  -H "Paidy-Version: 2018-04-10" \
  -H "Authorization: Bearer $secret_key" \
  -d $'{
         "wallet_id": "default",
         "reason": {
            "code": "consumer.requested",
            "description": "Consumer wants to continue with the subscription."
         }
      }'

Each merchant will have different reasons for why they may want to resume a token, depending on the products they sell, their business practices, and their customer service policies. The following are just a few examples of why a merchant may want to resume a token they had previously suspended:

  • If the token was suspended because the consumer called to dispute a charge that was made using the token, and the dispute has been resolved.
  • If the consumer called to renew a subscription they had temporarily put on hold (for example, if they were going to be away).
  • If you were having issues with the consumer and you temporarily put the account on hold (for example, until they paid their bill) and the issues have been resolved.
  • If there was suspicious activity using this token, but your investigation confirmed that everything was okay.

You must include the reason for the change in status in the request. For the reason code, use one of the values in the following table. If you send a code that is not listed here, the system returns an error. You can use the description field to give additional details around the reason for the suspension.

  • CODE

    USE

  • consumer.requested

    Send this code if the consumer has called you to request the token be resumed.

  • merchant.requested

    Send this code if you want to resume the token.

  • general

    Send this code in any other scenario.

Paidy verifies the token is SUSPENDED and resumes the token. If successful, the status of the token is updated to ACTIVE and you can once again create a payment.

Tokens can be resumed by the merchant using the API or by the consumer by calling Paidy Support. When a token is resumed, either by you or by a consumer, you will receive a webhook notification (if you have webhooks configured) alerting you to the change.

  Deleting a token

To delete a token, you send a POST request to the `/tokens/{id}/delete` endpoint, where {id} is the Paidy token ID. This request does not actually delete the token, but it permanently disables it so it can no longer be used for new payments. However, you can still retrieve the token object via the API.

Tokens can only be deleted by the merchant using the API. A token to be deleted can be in either the ACTIVE or SUSPENDED state.

token delete

Example:

curl -X "POST" "https://api.paidy.com/tokens/tok_WK5KjCEAAA0RvPp9/delete" \
  -H "Content-Type: application/json" \
  -H "Paidy-Version: 2018-04-10" \
  -H "Authorization: Bearer $secret_key" \
  -d $'{
         "wallet_id": "default",
         "reason": {
            "code": "subscription.expired",
            "description": "This subscription no longer available."
         }
      }'

Each merchant will have different reasons for why they may want to delete a token, depending on the products they sell, their business practices, and their customer service policies. The following are just a few examples of why a merchant may want to delete a token:

  • If the consumer has called to cancel a subscription.
  • If you are having recurring issues with a consumer and you want to cancel the subscription.
  • If there is some suspicious activity using this token and your investigation confirmed the token had been used fraudulently.

You must include the reason for the deletion in the request. For the reason code, use one of the values in the following table. If you send a code that is not listed here, the system return an error. You can use the description field to give additional details around the reason for the suspension.

  • CODE

    USE

  • consumer.requested

    Consumer calls the merchant to delete or cancel the token.

  • subscription.expired

    A subscription or campaign is finished.

  • merchant.requested

    Send this code if you want to delete the token.

  • fraud.detected

    Token cancelled because fraudulent activity detected.

  • general

    Send this code in any other scenario.

If the result is successful, the status of the token is updated to DELETED and if you try to create a payment using that token, Paidy will return an error.

  Retrieving a token

If you want to verify a token's status or see who suspended a token for example, you can retrieve the token object via the API. Only the specified token object will be returned.

retrieve token

To retrieve a token, send a GET request to the `/tokens/{id}` endpoint, where {id} is the Paidy token ID. Example:


curl -X "GET" "https://api.paidy.com/tokens/tok_WK5KjCEAAA0RvPp9" \
  -H "Content-Type: application/json" \
  -H "Paidy-Version: 2018-04-10" \
  -H "Authorization: Bearer $secret_key" \
  -d $'{}'

Unlike the "retrieve all" request which only returns tokens in an ACTIVE or SUSPENDED state, you can use this request to retrieve a token if is in the ACTIVE, SUSPENDED, or DELETED state.

  Retrieving all tokens

You can retrieve a list of all tokens for all your consumers via the API. Paidy will only return the list of all active and suspended tokens; it does not return the tokens that have been permanently "disabled".

retrieve all tokens

To retrieve all tokens, send a GET request to the `/tokens/` endpoint. Example:


curl -X "GET" "https://api.paidy.com/tokens/" \
 -H "Content-Type: application/json" \
 -H "Paidy-Version: 2018-04-10" \
 -H "Authorization: Bearer $secret_key" \
 -d $'{}'

An array of token objects is returned and the tokens are listed in descending order with newest token first. You can use this request to verify the list of tokens created each day.