{

Subscriptions

Create and list subscriptions, and start recurring payments

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 '{
        "order_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'.

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.
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 Enum(50) 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.
_+ consideredsafe 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"
            }
        ]
    }'