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 and interval_count = 1;
Charging every 3 weeks: interval = week and interval_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"
    }
}