Subscription Events
Introduction
Whenever an update occurs in a subscription, you will receive a notification. Subscription events are related to charge attempts, status changes, or changes in the subscription payment method.
Subscription Events
Charge attempt
When a subscription begins its billing period, we will attempt to bill your customer. If the charge is successful, you will receive a notification event "Subscription charged successfully". Otherwise, the notification event will be "Subscription charged unsuccessfully". In this notification, we only send order and subscription data related to the current billing.
Subscription charged successfully
Postback notification when a subscription is successfully charged:
POST /v1/postback
Host: your_payback_notification_url.com
Content-Type: application/json
{
"latam_id": "7c0b8129-f556-4357-bb6e-8189c2943024",
"code": "88",
"status": "paid",
"name": "Customer's Name",
"email": "[email protected]"
"original_amount": "20,00"
"fee": "2,0"
"tax": "1,3",
"additional_value": "0",
"value": "21,70",
"reason": "",
"payer_info": [],
"subscription":{
"event": "Subscription charged successfully",
"id": "bgwt7v",
"status": "active"
"plan_id": "bvt6",
"never_expires": true
"current_billing_cycle": 1,
"number_of_billing_cycles": null,
"next_billing_date": "2024-01-13",
"paid_through_date": "2024-01-12",
"updated_at": "2023-12-13",
"failure_count": 0,
"transaction":{
"id": "6hjfw847",
"status": "paid",
"created_at": "2023-12-13",
"updated_at": "2023-12-13",
"amount": 10.0,
"card_last_digits": "0620",
"card_brand": "Visa"
}
}
}
Subscription charged unsuccessfully
Postback notification when a subscription is unsuccessfully charged:
POST /v1/postback
Host: your_payback_notification_url.com
Content-Type: application/json
{
"latam_id": "7c0b8129-f556-4357-bb6e-8189c2943024",
"code": "88",
"status": "paid",
"name": "Customer's Name",
"email": "[email protected]"
"original_amount": "20,00"
"fee": "2,0"
"tax": "1,3",
"additional_value": "0",
"value": "21,70",
"reason": "",
"payer_info": [],
"subscription":{
"event": "Subscription charged unsuccessfully",
"id": "bgwt7v",
"status": "overdue"
"plan_id": "bvt6",
"never_expires": true
"current_billing_cycle": 1,
"number_of_billing_cycles": null,
"next_billing_date": "2024-01-13",
"paid_through_date": "2024-01-12",
"updated_at": "2023-12-13",
"failure_count": 1,
"transaction":{
"id": "6hjfw847",
"status": "fail",
"created_at": "2023-12-13",
"updated_at": "2023-12-13",
"amount": 10.0,
"card_last_digits": "0620",
"card_brand": "Visa"
}
}
}
Params descriptions
| Param | Description |
|---|---|
| latam_id | Order ID in the latam system |
| code | The ID from your system |
| status | The current status of the order |
| name | Customer's name |
| Customer's email | |
| original_amount | Value without taxes/fees |
| fee | Latam Fee to create value in (%) |
| tax | Latam Tax, paid by the partner, value in BRL |
| additional_value | Equal to Tax but is paid by the customer |
| value | Value adding fee and tax or additional_value |
| reason | If we need to add a message about the status, by default is null |
| payer_info | is a hashed object containing the payer’s information |
| subscription | subscription associated with the order |
Subscription params descriptions
| Param | Description |
|---|---|
| event | Subscription event |
| id | Subscription ID |
| status | The current status of the subscription |
| plan_id | ID of the plan associated with the subscription |
| never_expires | Indicates whether the subscription will expire or not |
| current_billing_cycle | Billing cicle in months |
| number_of_billing_cycles | Number of billing cycles if not never expires |
| next_billing_date | Next billing date |
| paid_through_date | Date until which the subscription is still considered paid |
| updated_at | Date of last subscription update |
| failure_count | Count of failed charge attempts |
| transaction | Transaction of subscription |
Transaction params descriptions
| Param | Description |
|---|---|
| id | Transaction ID |
| status | The current status of the transaction |
| created_at | Transaction created date |
| updated_at | Date of last transaction update |
| amount | Transaction amount |
| card_last_digits | Last digits of the credit card associated with the transaction |
| card_brand | Brand of the credit card associated with the transaction |
Status change
Every time a subscription has its status change, you will receive a notification. In this notification we send all subscription data.
Change status to Active
A subscription goes to activated status when its first billing cycle payment is successful or when a subscription was overdue and was successfully charged.
POST /
Host: your_payback_notification_url.com
{
"event": "subscription activated"
"id": "bgwt7v",
"balance": 0.0,
"created_at": "2023-12-13",
"never_expires": true,
"plan_id": "bvt6",
"price": 10.0,
"status": "active",
"billing_day_of_month": 13,
"billing_period_end_date": "2024-01-12",
"billing_period_start_date": "2023-12-13",
"days_past_due": null,
"description": null,
"failure_count": 0,
"first_billing_date": "2023-12-13",
"next_billing_date": "2024-01-13",
"number_of_billing_cycles": null,
"paid_through_date": "2024-01-12",
"updated_at": "2023-12-13",
"card_last_digits": "0620",
"card_brand": "Visa"
"transactions": [
{
"id": "6hjfw847",
"status": "paid",
"created_at": "2023-12-13",
"updated_at": "2023-12-13",
"amount": 10.0,
"order_id": 121364879,
"card_last_digits": "0620",
"card_brand": "Visa",
"billing_cycle": 1
},
{
"id": "124sf47",
"status": "paid",
"created_at": "2023-12-13",
"updated_at": "2023-12-13",
"amount": 10.0,
"order_id": 121364879,
"card_last_digits": "0620",
"card_brand": "Visa",
"billing_cycle": 2
}
]
}
Change status to Overdue
A subscription goes to overdue status when it fails the first billing attempt.
POST /
Host: your_payback_notification_url.com
{
"event": "subscription overdue"
"id": "bgwt7v",
"balance": 0.0,
"created_at": "2023-12-13",
"never_expires": true,
"plan_id": "bvt6",
"price": 10.0,
"status": "overdue",
"billing_day_of_month": 13,
"billing_period_end_date": "2024-01-12",
"billing_period_start_date": "2023-12-13",
"days_past_due": null,
"description": null,
"failure_count": 1,
"first_billing_date": "2023-12-13",
"next_billing_date": "2024-01-13",
"number_of_billing_cycles": null,
"paid_through_date": "2024-01-12",
"updated_at": "2023-12-13",
"card_last_digits": "0620",
"card_brand": "Visa"
"transactions": [
{
"id": "6hjfw847",
"status": "paid",
"created_at": "2023-12-13",
"updated_at": "2023-12-13",
"amount": 10.0,
"order_id": 121364879,
"card_last_digits": "0620",
"card_brand": "Visa",
"billing_cycle": 1
},
{
"id": "124sf47",
"status": "fail",
"created_at": "2023-12-13",
"updated_at": "2023-12-13",
"amount": 10.0,
"order_id": 121364879,
"card_last_digits": "0620",
"card_brand": "Visa",
"billing_cycle": 2
}
]
}
Change status to Cancelled
A subscription goes to canceled status after all billing attempts have failed.
POST /
Host: your_payback_notification_url.com
{
"event": "subscription cancelled"
"id": "bgwt7v",
"balance": 0.0,
"created_at": "2023-12-13",
"never_expires": true,
"plan_id": "bvt6",
"price": 10.0,
"status": "cancelled",
"billing_day_of_month": 13,
"billing_period_end_date": "2024-01-12",
"billing_period_start_date": "2023-12-13",
"days_past_due": null,
"description": null,
"failure_count": 3,
"first_billing_date": "2023-12-13",
"next_billing_date": "2024-01-13",
"number_of_billing_cycles": null,
"paid_through_date": "2024-01-12",
"updated_at": "2023-12-13",
"card_last_digits": "0620",
"card_brand": "Visa"
"transactions": [
{
"id": "6hjfw847",
"status": "paid",
"created_at": "2023-12-13",
"updated_at": "2023-12-13",
"amount": 10.0,
"order_id": 121364879,
"card_last_digits": "0620",
"card_brand": "Visa",
"billing_cycle": 1
},
{
"id": "124sf47",
"status": "fail",
"created_at": "2023-12-13",
"updated_at": "2023-12-13",
"amount": 10.0,
"order_id": 121364879,
"card_last_digits": "0620",
"card_brand": "Visa",
"billing_cycle": 2
}
]
}
Change status to Expired
A subscription goes to expired status when its last billing cycle is successfully completed.
POST /
Host: your_payback_notification_url.com
{
"event": "subscription expired"
"id": "bgwt7v",
"balance": 0.0,
"created_at": "2023-12-13",
"never_expires": false,
"plan_id": "bvt6",
"price": 10.0,
"status": "expired",
"billing_day_of_month": 13,
"billing_period_end_date": "2024-01-12",
"billing_period_start_date": "2023-12-13",
"days_past_due": null,
"description": null,
"failure_count": 3,
"first_billing_date": "2023-12-13",
"next_billing_date": "2024-01-13",
"number_of_billing_cycles": null,
"paid_through_date": "2024-01-12",
"updated_at": "2023-12-13",
"card_last_digits": "0620",
"card_brand": "Visa"
"transactions": [
{
"id": "6hjfw847",
"status": "paid",
"created_at": "2023-12-13",
"updated_at": "2023-12-13",
"amount": 10.0,
"order_id": 121364879,
"card_last_digits": "0620",
"card_brand": "Visa",
"billing_cycle": 1
},
{
"id": "124sf47",
"status": "paid",
"created_at": "2023-12-13",
"updated_at": "2023-12-13",
"amount": 10.0,
"order_id": 121364879,
"card_last_digits": "0620",
"card_brand": "Visa",
"billing_cycle": 2
}
]
}
Params descriptions
| Param | Description |
|---|---|
| event | Subscription event |
| id | Subscription ID |
| balance | Subscription balance due |
| created_at | Subscription created date |
| never_expires | Indicates whether the subscription will expire or not |
| plan_id | ID of the plan associated with the subscription |
| price | Subscription price |
| status | The current status of the subscription |
| billing_day_of_month | Day of the month that the subscription is charged |
| billing_period_end_date | End date of the current billing cycle |
| billing_period_start_date | Start date for the current billing period |
| days_past_due | Number of days that the subscription is overdue |
| description | Subscription description |
| failure_count | Count of failed charge attempts |
| first_billing_date | The day the subscription starts billing |
| next_billing_date | Day when the next billing cycle begins |
| number_of_billing_cycles | Number of billing cycles if not never expires |
| paid_through_date | Date until which the subscription is still considered paid |
| updated_at | Date of last subscription update |
| card_last_digits | Last digits of the credit card associated with the subscription |
| card_brand | Brand of the credit card associated with the subscription |
| transactions | Subscription transactions |
Transactions Params
| Param | Description |
|---|---|
| id | Transaction ID |
| status | The current status of the transaction |
| created_at | Transaction created date |
| updated_at | Date of last transaction update |
| amount | Transaction amount |
| order_id | the order ID associated with the transaction |
| card_last_digits | Last digits of the credit card associated with the transaction |
| card_brand | Brand of the credit card associated with the subscription |
| billing_cycle | Billing cycle number |
Subscription Update
Every time the payment method associated with a subscription changes, you will receive a notification.
POST /
Host: your_payback_notification_url.com
Content-Type: application/json
{
"event": "subscription updated"
"id": "bgwt7v",
"created_at": "2023-12-13",
"never_expires": false,
"plan_id": "bvt6",
"price": 10.0,
"status": "expired",
"billing_day_of_month": 13,
"billing_period_end_date": "2024-01-12",
"billing_period_start_date": "2023-12-13",
"days_past_due": null,
"description": null,
"failure_count": 1,
"first_billing_date": "2023-12-13",
"next_billing_date": "2024-01-13",
"number_of_billing_cycles": 3,
"paid_through_date": "2024-01-12",
"updated_at": "2023-12-13",
"card_last_digits": "1020",
"card_brand": "Mastercard"
"transactions": [
{
"id": "6hjfw847",
"status": "paid",
"created_at": "2023-12-13",
"updated_at": "2023-12-13",
"amount": 10.0,
"order_id": 121364879,
"card_last_digits": "0620",
"card_brand": "Visa",
"billing_cycle": 1
},
{
"id": "124sf47",
"status": "paid",
"created_at": "2024-01-13",
"updated_at": "2024-01-13",
"amount": 10.0,
"order_id": 121364879,
"card_last_digits": "0620",
"card_brand": "Visa",
"billing_cycle": 2
},
{
"id": "5342hyg",
"status": "paid",
"created_at": "2024-01-13",
"updated_at": "2024-01-13",
"amount": 10.0,
"order_id": 121364879,
"card_last_digits": "0620",
"card_brand": "Visa",
"billing_cycle": 3
}
]
}
Params descriptions
| Param | Description |
|---|---|
| event | Subscription event |
| id | Subscription ID |
| balance | Subscription balance due |
| created_at | Subscription created date |
| never_expires | Indicates whether the subscription will expire or not |
| plan_id | ID of the plan associated with the subscription |
| price | Subscription price |
| status | The current status of the subscription |
| billing_day_of_month | Day of the month that the subscription is charged |
| billing_period_end_date | End date of the current billing cycle |
| billing_period_start_date | Start date for the current billing period |
| days_past_due | Number of days that the subscription is overdue |
| description | Subscription description |
| failure_count | Count of failed charge attempts |
| first_billing_date | The day the subscription starts billing |
| next_billing_date | Day when the next billing cycle begins |
| number_of_billing_cycles | Number of billing cycles if not never expires |
| paid_through_date | Date until which the subscription is still considered paid |
| updated_at | Date of last subscription update |
| card_last_digits | Last digits of the credit card associated with the subscription |
| card_brand | Brand of the credit card associated with the subscription |
| transactions | Subscription transactions |
Transactions Params
| Param | Description |
|---|---|
| id | Transaction ID |
| status | The current status of the transaction |
| created_at | Transaction created date |
| updated_at | Date of last transaction update |
| amount | Transaction amount |
| order_id | the order ID associated with the transaction |
| card_last_digits | Last digits of the credit card associated with the transaction |
| card_brand | Brand of the credit card associated with the subscription |
| billing_cycle | Billing cycle number |
Order Status meanings
| Status | Meaning |
|---|---|
| paid | Order was paid with success |
| expired | Order was not paid at the available time |
| analysis | Order needs to be checked by our support team |
| reversed | Order value was paid back to customer |
| canceled | Order was canceled by reasons like: Manual analysis, fraud, etc |
Subscription Status meanings
| Status | Meaning |
|---|---|
| active | Subscription is active and all payments are up to date |
| overdue | Subscription payment is due. We will attempt to make charges for up to 1 week. After that, the subscription is cancelled |
| cancelled | Subscription is cancelled. When you make a request or when all billing attempts fail |
| expired | Subscription is expired. When the paid_through_date of the last billing cycle is exceeded |
Transaction Status meanings
| Status | Meaning |
|---|---|
| awaiting payment | Transaction still no payment attempt |
| paid | Transaction paid successfully |
| failed | Transaction failed payment attempt. When the last charge attempt made was unsuccessful |
| reversed | Transaction is reversed. Only when you request |
We expect that your system returns to ours: status code 200. If not, we’ll retry 5 more times.