Subscriptions

​

Example Use Cases

​

API Required

1. Create Purchase API
2. Charge Token API

​

Two fields that are easy to mix up

• is_recurring_token — “is this Purchase valid to be USED AS a recurring token?” true only when a recurring token was actually saved for this Purchase. When it is true, this Purchase’s id may be passed as the recurring_token in POST /purchases/{id}/charge/ to bill the same payment method (same card) again.
• recurring_token — “was this Purchase PAID USING a recurring token?” Holds the id of the token Purchase that paid this one, or null when it was paid with a newly entered card.

• A paid Purchase does not automatically carry a usable token. A token is saved only when the payment was enrolled for it — force_recurring: true on a hosted checkout, or remember_card=on with direct_post — and only once the card is validated/paid. Never assume id is chargeable just because the Purchase is paid.
• A Purchase paid by a token has recurring_token set and is_recurring_token: false: it was billed with an existing token, so it does not become a new token itself.
• The very first Purchase in a subscription is the reverse: it has is_recurring_token: true (it can be charged later) and a null recurring_token (nothing paid it but the customer’s card).
• Charging a Purchase that was never enrolled returns invalid_recurring_token (see Errors). Do not retry; re-prompt the buyer for a new card.

​

Example Cases

1. Subscription With Free Trial
2. Subscription With Registration Fee

​

1) Subscription With Free Trial

1. Create a registration fee using the Purchases API
   - get checkout_url from the response body to be used as a payment link
   - get id from the response body to be used as a token
   Note: Alan’s card must be validated in order for the token to be usable. Confirm this by checking that the Purchase’s is_recurring_token is true after the payment completes - a paid Purchase is not automatically a usable token.

{
  "client": {
    "email": "customer@example.com",
    "full_name": "Alan"
  },
  "purchase": {
    "products": [
      {
        "name": "Free Trial",
        "price": 0
      }
    ]
  },
  "skip_capture" : true,
  "brand_id": "<<Brand_id>>"
}

2. Create a monthly subscription using the Purchases API
   - get id from the response body to be used as a payment link

{
  "client": {
    "email": "customer@example.com",
    "full_name": "Alan"
  },
  "purchase": {
    "products": [
      {
        "name": "Subscription fee",
        "price": 500
      }
    ]
  },
  "brand_id": "<<Brand_id>>"
}

3. Charge subscription fee id with registration fee id using Charge token API
   Example API : …/purchases/monthly_subscription_fee_id/charge/

{
  "recurring_token" : "<<free_trial_id>>"
}

​

2) Subscription With Registration Fee

1. Create a registration fee using the Purchases API
   - get checkout_url from the response body to be used as a payment link
   - get id from the response body to be used as a token
   Note: Alan’s registration fee must be paid in order for the token to be usable. Confirm by checking that the Purchase’s is_recurring_token is true - not merely that status is paid.

{
  "client": {
    "email": "customer@example.com",
    "full_name": "Alan"
  },
  "purchase": {
    "products": [
      {
        "name": "Registration Fee",
        "price": 2000
      }
    ]
  },
  "payment_method_whitelist" : ["visa", "mastercard", "maestro"],
  "force_recurring" : true,
  "brand_id": "<<Brand_id>>"
}

2. Create a monthly subscription using the Purchases API
   - get id from the response body to be used as a payment link

{
  "client": {
    "email": "customer@example.com",
    "full_name": "Alan"
  },
  "purchase": {
    "products": [
      {
        "name": "Subscription fee",
        "price": 500
      }
    ]
  },
  "brand_id": "<<Brand_id>>"
}

3. Charge subscription fee id with registration fee id using Charge token API
   Example API : …/purchases/monthly_subscription_fee_id/charge/

{
  "recurring_token" : "<<registration_fee_id>>"
}

​

Testing Integration

• 4444 3333 2222 1111 - non-3D Secure card
• 5555 5555 5555 4444 - 3D Secure card

• any cardholder name
• any expiry no earlier than the current month/year
• CVC = 123

​

FAQ

1. Does CHIP handle the automatic renewal of subscriptions?
   No, CHIP does not handle automatic renewal. What CHIP offers is the ability to save and charge a customer’s saved card. The automatic renewal logic must be implemented on the merchant’s side, for example using a cron job or other scheduling mechanism.
2. What happens if I accidentally charge the customer’s card twice?
   Once the payment link is paid, any subsequent payment attempt will be blocked. As a result, the likelihood of a double charge issue is extremely low.
3. What is the token tied to?
   The token is tied to brand_id.
4. How is the token referenced?
   The token uses customer_email as a reference.
5. Where can I see my customer’s tokens?
   You can list the tokens for a customer using the List Token API.
6. How do I delete the token?
   You can delete a token using the Delete Token API.