Change subscription credit card

PATCH/subscriptions/{subscriptionId}/credit-card

Replaces the credit card of a subscription of the business.

Tokenize the new card with the Easyflow JavaScript SDK and send the token in creditCard.token. The token goes only in this request: no response and no webhook returns it. The next recurrences are charged to the new card saved in the subscription, without a new token.
The API key must have write access to subscriptions, and its user must be a collaborator of the business sent in business-id. Only the business that owns the subscription can change its card.
Recurrences after the first one that are delayed or failed, and whose payments all failed, are sent to be charged on the new card. Their IDs come in retriedRecurrenceIds, and the result of each charge arrives by webhook.
A recurrence is left out of retriedRecurrenceIds, and is not charged by this request, when the subscription is active and the next automatic retry of the recurrence is already due (the automatic retry charges it), or when the recurrence was retried in the last 10 minutes.
When a recurrence is sent to be charged and the subscription is inactive, it becomes active again.
Easyflow sends the subscription.updated webhook.
A subscription that is canceled or expired cannot have its card changed.
Up to 30 requests per minute for each user (all API keys of the same user share the limit). Above that, the API returns 429 with the Retry-After header.

Request

curl --request PATCH \
  --url 'https://9iq81tsdy4.execute-api.sa-east-1.amazonaws.com/subscriptions/SUBSCRIPTION_ID/credit-card' \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'x-api-secret: YOUR_API_SECRET' \
  --header 'business-id: YOUR_BUSINESS_ID' \
  --header 'Content-Type: application/json' \
  --data '{
  "creditCard": {
    "token": "YOUR_CARD_TOKEN",
    "last4Numbers": "4444",
    "holderName": "MARIA SILVA",
    "expiresAtMonth": 6,
    "expiresAtYear": 2031,
    "flag": "mastercard"
  },
  "buyer": {
    "device": {
      "ip": "203.0.113.10",
      "fingerprintId": "9f2c4e1a7b",
      "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)"
    }
  }
}'

const response = await fetch('https://9iq81tsdy4.execute-api.sa-east-1.amazonaws.com/subscriptions/SUBSCRIPTION_ID/credit-card', {
  method: 'PATCH',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'x-api-secret': 'YOUR_API_SECRET',
    'business-id': 'YOUR_BUSINESS_ID',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "creditCard": {
      "token": "YOUR_CARD_TOKEN",
      "last4Numbers": "4444",
      "holderName": "MARIA SILVA",
      "expiresAtMonth": 6,
      "expiresAtYear": 2031,
      "flag": "mastercard"
    },
    "buyer": {
      "device": {
        "ip": "203.0.113.10",
        "fingerprintId": "9f2c4e1a7b",
        "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)"
      }
    }
  }),
});

const data = await response.json();
console.log(data);

import requests

url = "https://9iq81tsdy4.execute-api.sa-east-1.amazonaws.com/subscriptions/SUBSCRIPTION_ID/credit-card"
headers = {
    "x-api-key": "YOUR_API_KEY",
    "x-api-secret": "YOUR_API_SECRET",
    "business-id": "YOUR_BUSINESS_ID",
}
payload = {
    "creditCard": {
        "token": "YOUR_CARD_TOKEN",
        "last4Numbers": "4444",
        "holderName": "MARIA SILVA",
        "expiresAtMonth": 6,
        "expiresAtYear": 2031,
        "flag": "mastercard",
    },
    "buyer": {
        "device": {
            "ip": "203.0.113.10",
            "fingerprintId": "9f2c4e1a7b",
            "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
        },
    },
}

response = requests.patch(url, headers=headers, json=payload)
print(response.json())

Response

{
  "statusCode": 200,
  "data": {
    "subscriptionId": "2d1e0f9a-8b7c-4d6e-9f5a-4b3c2d1e0f9a",
    "status": "active",
    "creditCard": {
      "last4Numbers": "4444",
      "holderName": "MARIA SILVA",
      "expiresAtMonth": 6,
      "expiresAtYear": 2031,
      "flag": "mastercard"
    },
    "retriedRecurrenceIds": [
      "5e4d3c2b-1a09-4f8e-b7d6-c5b4a3928170"
    ]
  }
}

{
  "message": "Invalid param: []",
  "error": "Bad Request",
  "statusCode": 400,
  "errorCode": "string"
}

Generated from the schema

{
  "message": "Unauthorized",
  "error": "Unauthorized",
  "statusCode": 401
}

Generated from the schema

{
  "message": "Forbidden resource",
  "error": "Forbidden",
  "statusCode": 403
}

Generated from the schema

{
  "statusCode": 422,
  "message": "Unprocessable Entity",
  "error": "Unprocessable Entity"
}

{
  "statusCode": 429,
  "message": "Too many requests, retry after the Retry-After seconds"
}

Generated from the schema

{
  "statusCode": 500,
  "message": "Internal Server Error"
}

Generated from the schema

Headers

x-api-keystringrequired
Api key provided on integrations tab in Easyflow platform.
x-api-secretstringrequired
Api Secret provided on integrations tab in Easyflow platform.
business-idstringrequired
Identifier of the business the request refers to. The user of your API key must be linked to this business, as explained in The business identifier. A value that is not a business identifier returns 400 with Invalid param: [businessId], and a business that the user is not linked to returns 403.