Support

Recurring Billing

The Payment Gateway allow merchants to receive recurring credit card or check payments using subscriptions.

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

[2] 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"
    }
}