Create a Subscription
Credit Card: POST https://gateway-api.paycertify.com/api/subscriptions
Check: POST https://gateway-api.paycertify.com/api/checks/subscriptions
To create a subscription, you should define when and how much to charge your customer. To start billing, simply create a subscription and then the Gateway will handle the entire billing flow for you. The charging period should be defined by the interval
and interval_count
fields. Being interval
the period of time to calculate the next charge and interval_count
being the interval
number that we should wait until the next charge. For example:
- Charging every month:
interval = month
andinterval_count = 1
; - Charging every 3 weeks:
interval = week
andinterval_count = 3
.
Subscriptions should also receive the start_date
and end_date
fields, which means the start and end date of the subscription, respectively. The first charge will always occur on the start_date
. The next payment cycles will be automatically calculated by the Gateway. The whole period until start_date
will be considered as trial and you can charge your customer for this period filling the trial_amount
field.
Beware: filling trial_amount
and a start_date
too close may result in undesirable behavior. It is recommended to use trial_amount
with a start_date
equals to the current date + the configured interval.
The subscription routine runs every day at 00:59 PST (07:59 UTC) and performs the charge for all the merchant accounts. The system collects the active subscriptions that should be charged by comparing the start_date
(before the current date). This means that a monthly subscription created with the start_date equals August 1st will be charged every month on the 2nd at 00:59 PST.
Parameter | Type | Length | Presence | Description | Example |
---|---|---|---|---|---|
processor_id |
uuid |
36 | Optional[1] | The Processor record ID | 41f00869-d7b3-413e-9476-9ef1a8bc2f28 |
description |
string |
1-255 | Required | A brief description of the current subscription | Monthly tennis club signature |
start_date |
string |
string | Required | The date and time when subscription should start Y-m-d h:m:s format. |
2018-10-01 12:00:00 |
end_date |
string |
string | Required | The date and time when subscription should end Y-m-d h:m:s format. |
2019-10-01 12:00:00 |
interval |
string |
1-255 | Required | Time period measure you require (day , week , month ) |
day |
interval_count |
number |
1-255 | Required | Number of interval between payments |
10 |
amount |
number |
0.01-9999999 | Required | Amount to be charged every recurring cycle | 3.56 |
trial_amount |
number |
0.01-9999999 | Optional | The amount that will be charged in subscription creation. | 3.56 |
card_number |
string |
8-19 | Required[2] | The credit card to charge | 411111111111111 |
card_expiry_month |
string |
2 | Required[2] | The expiration month with two positions | 01 |
card_expiry_year |
string |
4 | Required[2] | The expiration year with four positions | 2021 |
card_cvv |
string |
3-4 | Optional | 3 or 4 digit card verification code | 123 |
account_number |
string |
0-17 | Required[3] | The bank account to charge | 10000000000000 |
check_number |
string |
0-15 | Required[3][4] | The identifying number of the “check”. This should be unique per transaction. | 100000 |
routing_number |
string |
9 | Required[3] | The ABA routing number of the bank account you wish to charge. | 061103852 |
merchant_subscription_id |
string |
1-255 | Optional | A merchant assigned identifier (your subscription ID) | my-subscription-id-0001 |
first_name |
string |
1-255 | Required | Customer’s first name | John |
last_name |
string |
1-255 | Required | Customer’s last name | Doe |
email |
string |
1-255 | Optional | Customer’s email | [email protected] |
mobile_phone |
string |
11-15 | Optional | Customer’s phone | 11231231234 |
street_address_1 |
string |
1-255 | Required | Billing address first line (street address) | 59 N Santa Cruz Avenue |
street_address_2 |
string |
1-255 | Optional | Billing address second line (suite, apt, etc) | Suite M |
city |
string |
1-255 | Required | Billing address city | Los Gatos |
state |
string |
2 | Required | Billing address state abbreviation | CA |
country |
string |
2 | Required | Billing address country abbreviation | US |
zip |
string |
5-6 | Required | Billing address postal code | 95030 |
shipping_street_address_1 |
string |
1-255 | Optional | Shipping address first line (street address) | 59 N Santa Cruz Avenue |
shipping_street_address_2 |
string |
1-255 | Optional | Shipping address second line (suite, apt, etc) | Suite M |
shipping_city |
string |
1-255 | Optional | Shipping address city | Los Gatos |
shipping_state |
string |
2 | Optional | Shipping address state abbreviation | CA |
shipping_country |
string |
2 | Optional | Shipping address country abbreviation | US |
shipping_zip |
string |
2-255 | Optional | Shipping address postal code | 95030 |
status_url |
string |
1-255 | Optional | A Valid HTTP/HTTPS url to be reached on every updated on the subscription | https://yourdomain.com/status/callback |
[1] If processor_id
has not been provided, the gateway will pick one randomly.
[2] Required for credit card subscriptions only.
[3] Required for check subscriptions only.
[4] Subsequent charges will generate random check numbers. Beware that this will make some check numbers unavailable.
Parameter | Type | Length | Description | Example |
---|---|---|---|---|
subscription.id |
uuid |
36 | The Subscription record ID | e57aa3bf-a3df-4056-b1f2-d4de7252fe99 |
subscription.merchant_id |
uuid |
36 | The user’s merchant ID | e57aa3bf-a3df-4056-b1f2-d4de7252fe99 |
subscription.user_id |
uuid |
36 | The user’s ID | e57aa3bf-a3df-4056-b1f2-d4de7252fe99 |
subscription.status |
string |
6-8 | Result of Subscription request | trialing |
subscription.description |
string |
1-255 | A brief description of the current subscription | Monthly tennis club signature |
subscription.interval |
string |
3-5 | Time period measure you require (day , week , month ) |
day |
subscription.interval_count |
number |
- | Number of interval between payments |
1 |
subscription.processor_id |
uuid |
36 | The processor’s ID | e57aa3bf-a3df-4056-b1f2-d4de7252fe99 |
subscription.merchant_subscription_id |
string |
1-255 | A merchant assigned identifier (your subscription ID) | MY-ORDER |
subscription.first_name |
string |
1-255 | Customer’s first name | John |
subscription.last_name |
string |
1-255 | Customer’s last name | Doe |
subscription.street_address_1 |
string |
1-255 | Billing address first line (street address) | 59 N Santa Cruz Avenue |
subscription.street_address_2 |
string |
1-255 | Billing address second line (suite, apt, etc) | Suite M |
subscription.city |
string |
1-255 | Billing address city | Los Gatos |
subscription.state |
string |
2 | Billing address state abbreviation, ISO 3166-2 format. | CA |
subscription.country |
string |
2 | Billing address country abbreviation, ISO 3166-1 alpha-2 format. | US |
subscription.zip |
string |
2-255 | Billing address postal code | 95030 |
subscription.email |
string |
1-255 | Customer’s email | [email protected] |
subscription.mobile_phone |
string |
11-15 | Customer’s phone in E.164 format | +11231231234 |
subscription.amount |
number |
0.01-9999999 | Amount to be charged every recurring cycle | 3.56 |
subscription.trial_amount |
number |
0.01-9999999 | The amount charged on Subscription creating, used for paid trial periods. | 3.56 |
subscription.start_date |
datetime |
19 | The date and time when subscription should start Y-m-d h:m:s format. |
2018-10-01 12:00:00 |
subscription.end_date |
datetime |
19 | The date and time when subscription should end Y-m-d h:m:s format. |
2019-10-01 12:00:00 |
subscription.next_cycle_date |
datetime |
19 | The date and time of the next charge Y-m-d h:m:s format. |
2019-10-01 12:00:00 |
subscription.transactions |
array |
- | Listing of Subscription related transactions | - |
subscription.updated_at |
datetime |
19 | Last time this event was updated, on ISO 8601 UTC | 2018-02-16T16:33:40+00:00 |
subscription.created_at |
datetime |
19 | Time that event was created, on ISO 8601 UTC | 2018-02-16T16:33:40+00:00 |
subscription.card_number |
string |
8-19 | Redacted card number | 411111**1111 |
subscription.card_expiry_month |
string |
2 | The expiration month with two positions | 01 |
subscription.card_expiry_year |
string |
4 | The expiration year with four positions | 2021 |
curl --request POST \
--url https://gateway-api.paycertify.com/api/subscriptions \
--header 'Authorization: Bearer YOUR_API_TOKEN' \
--form 'amount=1.00' \
--form 'description=Monthly tennis club signature' \
--form 'start_date=2018-09-07' \
--form 'end_date=2018-10-07' \
--form 'interval=day' \
--form 'card_number=4111111111111111' \
--form 'merchant_subscription_id=MY-ORDER' \
--form 'interval_count=1' \
--form 'card_expiry_month=01' \
--form 'card_expiry_year=2021' \
--form 'card_cvv=999' \
--form 'first_name=John' \
--form 'last_name=Doe' \
--form 'street_address_1=59 N Santa Cruz Avenue' \
--form 'street_address_2=Suite M' \
--form 'city=Los Gatos' \
--form 'state=CA' \
--form 'country=US' \
--form 'mobile_phone=+11231231234' \
--form '[email protected]' \
--form 'merchant_transaction_id=my-order-id-0001' \
--form 'zip=95030'
{
"subscription": {
"id": "e57aa3bf-a3df-4056-b1f2-d4de7252fe99",
"merchant_id": "c8444f15-887b-45bf-a143-a1112962f600",
"user_id": "03825915-d9ac-48c9-9bda-8055ed415c25",
"status": "trialing",
"description": "Monthly tennis club signature",
"interval": "day",
"interval_count": "1",
"processor_id": "5364358a-b8f7-4f45-b600-7fc614bf0285",
"merchant_subscription_id": "MY-ORDER",
"first_name": "John",
"last_name": "Doe",
"street_address_1": "59 N Santa Cruz Avenue",
"street_address_2": "Suite M",
"city": "Los Gatos",
"state": "CA",
"country": "US",
"zip": "41970",
"email": "[email protected]",
"mobile_phone": "+11231231234",
"amount": "1.00",
"trial_amount": null,
"start_date": "2018-07-09T00:00:00+0000",
"end_date": "2018-07-10T00:00:00+0000",
"next_cycle_date": "2018-09-11T21:24:19+0000",
"transactions": [
{
"id": "3410596f-d596-42d4-9811-41d43868e984",
"merchant_id": "455a1c64-385b-41b2-a56f-34bf6c5c5335",
"user_id": "6e064bf5-0e18-466b-811b-f967e8d73b9f",
"processor_id": "30ff7682-6ec7-48f3-8d7a-62319a9c3c59",
"merchant_transaction_id": "REC-MY-ORDER-0000",
"card_number": "411111******1111",
"card_brand": "visa",
"card_expiry_month": "01",
"card_expiry_year": "2021",
"first_name": "John",
"last_name": "Doe",
"street_address_1": "59 N Santa Cruz Avenue",
"street_address_2": "Suite M",
"city": "Los Gatos",
"state": "CA",
"country": "US",
"zip": "95030",
"email": "[email protected]",
"mobile_phone": "+11231231234",
"updated_at": "2018-02-16T16:33:40+00:00",
"created_at": "2018-02-16T16:33:39+00:00",
"events": [
{
"id": "84a8ab86-ee0e-47d4-8686-4e42fa58355e",
"success": true,
"threeds_response": null,
"avs_response": null,
"event_type": "refund",
"amount": "1.00",
"ip_address": "127.0.0.1",
"processor_code": "00",
"processor_message": "APPROVAL TAS656 ",
"processor_transaction_id": "000000000252616",
"processor_threeds_response": null,
"processor_avs_response": "0",
"updated_at": "2018-02-16T16:33:40+00:00",
"created_at": "2018-02-16T16:33:39+00:00"
},
{
"id": "84a8ab86-ee0e-47d4-8686-1e12fa12345e",
"success": true,
"threeds_response": null,
"avs_response": null,
"event_type": "sale",
"amount": "1.00",
"ip_address": "127.0.0.1",
"processor_code": "00",
"processor_message": "APPROVAL TAS656 ",
"processor_transaction_id": "000000000252616",
"processor_threeds_response": null,
"processor_avs_response": "0",
"updated_at": "2018-02-16T16:33:40+00:00",
"created_at": "2018-02-16T16:33:39+00:00"
}
]
}
],
"updated_at": "2018-09-10T21:24:19+0000",
"created_at": "2018-09-10T21:24:19+0000",
"card_number": "411111******1111",
"card_expiry_month": "01",
"card_expiry_year": "2021"
}
}