Subscriptions

Create and list subscriptions, and start recurring payments

• Create a new subscription
• Create a new order
• Start a Recurring Payment
• Return details of subscription

Create a new subscription

Create a new subscription.

POST /ps/api/public/v1/merchants/{merchant_key}/subscriptions

Identifiers

Name	Type	Description
merchant_key	MerchantKey	The key of the merchant.

Parameters

Not applicable.

Request

Field	Type	M	Description
subscription_reference	String(1, 255)	M	The subscription reference from the merchant.

Response

Not applicable.

HTTP Status

Status	Meaning
201 (Created)	The subscription is successfully created.
400 (Bad Request)	The request was not valid.
401 (Unauthorized)	Authorization header missing or invalid.
403 (Forbidden)	The merchant key is not allowed.

Create subscription example

> curl \
    -X POST \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Basic RG9jZGF0YVBGOkJXazJhZkpV' \
    https://testsecure.docdatapayments.com/ps/api/public/v1/merchants/4ef08825-993a-424d-a769-3ee97116a1b6/subscriptions \
    -d '{
        "subscription_reference"   : "vk20210318a"
    }'

< Http 201 Created

Create a new order

Create a new order for a subscription. This is the same as creating a normal order, except the subscription reference needs to given in the url.

POST /ps/api/public/v1/merchants/{merchant_key}/subscriptions/{subscription_reference}/orders

This is the same as creating a normal order, except the subscription reference needs to given in the url.

It is advisable to supply a billing address for the shopper to be used on the mandate.

See Create a new order for more details.

Start a Recurring Payment

Starts a new subsequent-recurring payment for the given Order of a Subscription.

The payment details of the initial-recurring payment are used, which the shopper should have authorized previously using the menu or the Start Payment endpoint.

POST /ps/api/public/v1/merchants/{merchant_key}/subscriptions/{subscription_reference}/orders/{order_key}/payments

Identifiers

Name	Type	Description
merchant_key	MerchantKey	The key of the merchant.
subscription_reference	String(1, 255)	The subscription reference from the merchant.
order_key	OrderKey	The key of the order.

Parameters

Not applicable.

Request

Field	Type	M	Description
sca_exemption	Enum(32)	O	The requested exemption type. Default value is 'RECURRING'.
+ three_ri_authentication	Block	O	The 3RI authentication details.

Details about the 3RI authentication block and process can be found on 3RI Authentication.

For the field sca_exemption the following values are possible:

Status	Description
RECURRING	The payment is part of a scheduled subsequent transaction.
UNSCHEDULED	The payment is part of an unscheduled subsequent transaction. For example a top-up payment. Must be enabled on the merchant account.

Response

Field	Type	M	Description
id	PaymentIdentifier	M	The payment identifier.
status	Enum(32)	M	The authorization status of the payment.

For the field status the following values are possible:

Status	Description
CANCELED	The payment is canceled, due to an error.
AUTHENTICATION_REQUESTED	The shopper needs to complete the authentication request that is pushed to its device.
AUTHORIZED	The payment is authorized.

HTTP Status

Status	Meaning
201 (Created)	The payment is created.
202 (Accepted)	The payment is created and ended in canceled due to an error.
400 (Bad Request)	The request was not valid.
403 (Forbidden)	The merchant key is not correct.
404 (Not Found)	The reference for the subscription or the order key was not found.

Start recurring payment example

> curl \
    -X POST \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Basic RG9jZGF0YVBGOkJXazJhZkpV' \
    https://testsecure.docdatapayments.com/ps/api/public/v1/merchants/4ef08825-993a-424d-a769-3ee97116a1b6/subscriptions/vk20210318a/orders/B72AD93F3CBFC47BB2173361D5DE573D/payments \
    -d '{
    "sca_exemption" : "RECURRING"
    }'

< Http 201 Created 
<    '{
        "id"        : "pid2163180628t",
        "status"    : "AUTHORIZED"
     }'

Return details of subscription

Returns the details of a subscription including the orders.

GET /ps/api/public/v1/merchants/{merchant_key}/subscriptions/{subscription_reference}

Identifiers

Name	Type	Description
merchant_key	MerchantKey	The key of the merchant.
subscription_reference	String(1, 255)	The subscription reference from the merchant.

Parameters

Not applicable.

Request

Not applicable.

Response

Field	Type	M	Description
timestamp	DateTime	M	The date and time when the subscription was created.
method	PaymentMethod	C	The payment method, e.g. "IDEAL" or "SEPA_DIRECT_DEBIT". Only available when a initial-recurring payment was authorized.
mandate_number	String(1, 255)	C	The mandate number. Only available when a initial-recurring payment was authorized.
orders	Block[]	O	A list of orders on this subscription.
+ order_reference	String(1, 255)	M	The order reference from the merchant.
+ timestamp	DateTime	M	The date and time when the order was created.
+ order_key	OrderKey	M	The key of the order.
+ considered_safe	Block	C	The considered safe result. Only available when the order is considered safe.
+ + level	Enum(16)	M	The considered safe level for the order: "FASTEST", "FAST", "SAFE" or "SAFEST".
+ + timestamp	DateTime	M	The date and time in seconds when the order was considered safe. Formatted according ISO 8601 with timezone in UTC.

HTTP Status

Status	Meaning
200 (OK)	Success.
403 (Forbidden)	The merchant key is not correct.
404 (Not Found)	The reference for the subscription was not found.

Subscription Details example

> curl \
    -X GET \
    --header 'Authorization: Basic RG9jZGF0YVBGOkJXazJhZkpV' \
    https://testsecure.docdatapayments.com/ps/api/public/v1/merchants/4ef08825-993a-424d-a769-3ee97116a1b6/subscriptions/vk20170224p

< Http 200 Ok
<   '{
        "timestamp"     : "2017-02-24T17:08:13Z",
        "method"        : "SEPA_DIRECT_DEBIT",
        "mandate_number": "ddps-148795461791824269",
        "orders"        : [
            {
                "order_reference"   : "vk20170224p",
                "timestamp"         : "2017-02-24T17:08:31Z",
                "order_key"         : "F1499C097FFA533D46FB05D52680AB9A",
                "considered_safe"   : {
                    "level" : "SAFE",
                    "timestamp" : "2017-02-24T17:09:58Z"
                }
            },
            {
                "order_reference"   : "vk20170320b",
                "timestamp"         : "2017-02-25T09:31:22Z""
                "order_key"         : "29FF5671F59846D2E0F432A6E450B6AE"
            }
        ]
    }'