Subscriptions via credit card

Suggest Edits

Just like with a payment, credit card and holder details can be sent in the subscription creation request so that the payment is processed immediately. However, while in the case of a payment the customer's card is charged at the moment of creation, in the case of a subscription, the card is validated at the moment of creation, but the payment is only made on the due date of the first installment. It's important to note that the validation done at the moment of creation does not guarantee that the charge will be successful on the due date, as the card could have been canceled, expired, be without limit, among other issues, in the meantime.

To do this, when executing the subscription creation request, just send the credit card details along with the holder's details through the creditCard and creditCardHolderInfo objects. If the transaction is authorized, the subscription will be created, and the API will return HTTP 200. Otherwise, the subscription will not be persisted, and HTTP 400 will be returned.

📘

Tip!

If you want to create a subscription where the first charge is made at the time of creation, set nextDueDate to today's date.

Once the subscription with a credit card is created, the charge will be made monthly (or another defined frequency) on the customer's card until it becomes invalid or you remove the subscription.

🚧

Attention

  • If you choose to capture the customer's card details in the interface of your system, the use of SSL (HTTPS) is mandatory; otherwise, your account may be blocked for credit card transactions.
  • To avoid timeouts and consequently duplicate captures, we recommend setting a minimum timeout of 60 seconds for this request.

How to change the due date or the value?

To change the value or due date of a subscription, you must have tokenization active on your account.

This feature allows you to charge your customers recurrently without them needing to input all the credit card details again, securely through a token.

🚧

Attention

  • The tokenization feature is pre-enabled in Sandbox, and you can test it there. For use in production, it is necessary to request the activation of the feature from your account manager. The activation of the feature is subject to prior analysis and may be approved or denied based on the risks of the operation.
  • The token is stored per customer and cannot be used in transactions of other customers.

To edit the subscription, you don't need to inform the token, but it needs to be activated on your account.

Additionally, when updating the subscription value or payment method, only future installments will be affected. To update installments already created but not paid with the new payment method and/or new value, it's necessary to pass the parameter updatePendingPayments: true.

How to change the credit card of a subscription?

To change the credit card of a charge, you need to take the first pending charge of a subscription and pay it with the new card.

🚧

The charge will be paid at the moment you make the call to the endpoint. All other charges of the same subscription will have their data updated to the new card.

To get the open charges of a subscription, make a call to the endpoint to list charges of a subscription.

An array will be returned with all pending payments. Having their IDs, just make a call to the endpoint to pay a charge with a credit card.

{
  "creditCard": {
    "holderName": "marcelo h almeida",
    "number": "5162306219378829",
    "expiryMonth": "05",
    "expiryYear": "2021",
    "ccv": "318"
  },
  "creditCardHolderInfo": {
    "name": "Marcelo Henrique Almeida",
    "email": "[email protected]",
    "cpfCnpj": "24971563792",
    "postalCode": "89223-005",
    "addressNumber": "277",
    "addressComplement": null,
    "phone": "4738010919",
    "mobilePhone": "47998781877"
  }
}

How could I upgrade a subscription plan?

You might have a customer who subscribed to a monthly plan but wants to upgrade to a higher, more expensive plan in the middle of the period or switch to an annual plan. If you have tokenization active on your account, you can change the value of the subscription and/or date; otherwise, it's recommended to remove the current subscription and create a new one afterward.

If your customer has proportional values to settle, it's recommended to check the open charges, calculate the extra amount, generate a new charge for the proportional amount, and then edit your subscription for the new values and/or date.

Updated 14 days ago