{"_id":"59f86b3390da9f001c0618c0","project":"57336fd5a6a9c40e00e13a0b","version":{"_id":"59dfa5828b51880010b74ab6","project":"57336fd5a6a9c40e00e13a0b","__v":1,"createdAt":"2017-10-12T17:25:22.850Z","releaseDate":"2017-10-12T17:25:22.850Z","categories":["59dfa5828b51880010b74ab7","59dfa5828b51880010b74ab8","59dfa5828b51880010b74ab9","59dfa5828b51880010b74aba","59dfa5828b51880010b74abb","59dfa5828b51880010b74abc","59dfa5828b51880010b74abd","59dfa5828b51880010b74abe","59dfa5828b51880010b74abf","59dfa5828b51880010b74ac0","59dfa5828b51880010b74ac1","59dfa5828b51880010b74ac2","59dfa5828b51880010b74ac3","59dfa5828b51880010b74ac4","59dfa5828b51880010b74ac5"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":false,"codename":"3.23 Release","version_clean":"8976.0.0-JSON","version":"8976-JSON"},"category":{"_id":"59dfa5828b51880010b74abe","version":"59dfa5828b51880010b74ab6","project":"57336fd5a6a9c40e00e13a0b","__v":0,"sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-07-27T10:22:06.636Z","from_sync":false,"order":7,"slug":"subscriptions","title":"Subscriptions"},"user":"560d5913af97231900938124","__v":0,"parentDoc":null,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2017-10-31T12:23:15.891Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"examples":{"codes":[]},"results":{"codes":[]},"settings":"57ee593a21ceb20e0061959e","method":"post","auth":"optional","params":[],"url":"/recurring/ondemand"},"isReference":false,"order":6,"body":"If you manage your own subscriptions, the Create Merchant-Managed Subscription request enables you to set up a merchant-managed subscription, which associates an initial subscription charge with all recurring charges. \n\nTo process recurring subscription charges, you'll send a [Create Merchant-Managed Subscription Charge](doc:create-merchant-managed-subscription-charge) request.\n[block:callout]\n{\n  \"type\": \"success\",\n  \"title\": \"See the guide on using merchant-managed subscriptions\",\n  \"body\": \"For more information on working with merchant-managed subscriptions, see [Merchant-Managed Subscriptions](doc:subscription-management#section-merchant-managed-subscriptions).\"\n}\n[/block]\n<a class=\"btn btn-success\" href=\"#section-api-explorer\" role=\"button\">Try it in the API Explorer</a>\n\n###Request Content\n`charge` *object* &nbsp;&nbsp;&nbsp;<span style=\"color:#F37500\">**required**</span>, contains the following properties (see [charge](doc:charge)):\n\n&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;`amount` *decimal* &nbsp;&nbsp;&nbsp;<span style=\"color:#F37500\">**required**</span> for SEPA Direct Debit; optional otherwise\n\n&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;`currency` *string* &nbsp;&nbsp;&nbsp;<span style=\"color:#F37500\">**required**</span> \n\n&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;`vaultedShopperId` *integer* &nbsp;&nbsp;&nbsp;optional - do not include if sending `payerInfo`\n\n&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;`payerInfo` *object* &nbsp;&nbsp;&nbsp;optional - do not include if sending `vaultedShopperId` (see [payerInfo](doc:payer-info))\n\n&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;`paymentSource` *object* &nbsp;&nbsp;&nbsp;<span style=\"color:#F37500\">**required** for `payerInfo`</span>; optional for `vaultedShopperId` (see [paymentSource](doc:payment-source))\n\n&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;`softDescriptor` *string* &nbsp;&nbsp;&nbsp;optional\n\n&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;`descriptorPhoneNumber` *string* &nbsp;&nbsp;&nbsp;optional\n\n&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;`authorizedByShopper` &nbsp;&nbsp;&nbsp; *boolean* &nbsp;&nbsp;<span style=\"color:#F37500\">**required**</span> for SEPA Direct Debit&nbsp;&nbsp; value must be **true**\n\n&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;`transactionFraudInfo` *object* &nbsp;&nbsp;&nbsp;optional (see [transactionFraudInfo](doc:transaction-fraud-info))\n\n###Response Details\nIf successful, the response HTTP status code is 200 OK.\nThe response body contains the [charge](doc:charge) resource. \nThe `subscriptionId` appears in the response body (unless payment source was SEPA Direct Debit).\n\n<hr>\n\n##Examples\n\n###Request Examples\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -v -X POST https://sandbox.bluesnap.com/services/2/recurring/ondemand \\\\\\n-H 'Content-Type: application/json' \\\\\\n-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \\\\\\n-d '\\n{\\n  \\\"amount\\\": 45, \\n  \\\"currency\\\": \\\"USD\\\",\\n  \\\"payerInfo\\\": {\\n    \\\"firstName\\\": \\\"John\\\",\\n    \\\"lastName\\\": \\\"Doe\\\",\\n    \\\"zip\\\": \\\"12345\\\",\\n    \\\"country\\\": \\\"us\\\"\\n  },\\n  \\\"paymentSource\\\": {\\n    \\\"creditCardInfo\\\": {\\n      \\\"creditCard\\\": {\\n        \\\"expirationYear\\\": 2018,\\n        \\\"securityCode\\\": 111,\\n        \\\"expirationMonth\\\": \\\"05\\\",\\n        \\\"cardNumber\\\": 4012000033330026\\n      }\\n    }\\n  }\\n}'\",\n      \"language\": \"curl\",\n      \"name\": \"Create Merchant-Managed Subscription request: with credit card\"\n    },\n    {\n      \"code\": \"curl -v -X POST https://sandbox.bluesnap.com/services/2/recurring/ondemand \\\\\\n-H 'Content-Type: application/json' \\\\\\n-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \\\\\\n-d '\\n{\\n  \\\"amount\\\": 45, \\n  \\\"currency\\\": \\\"USD\\\", \\n  \\\"paymentSource\\\": {\\n    \\\"wallet\\\": {\\n      \\\"applePay\\\": {\\n        \\\"encodedPaymentToken\\\": \\\"eyJ0b2tliZ2l2ZW5OYW1lIjoiTG9kIiwiY291bnRye…\\\"\\n      }\\n    }\\n  }\\t\\n}'\",\n      \"language\": \"curl\",\n      \"name\": \"with Apple Pay\"\n    },\n    {\n      \"code\": \"curl -v -X POST https://sandbox.bluesnap.com/services/2/recurring/ondemand \\\\\\n-H 'Content-Type: application/json' \\\\\\n-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \\\\\\n-d '\\n{\\n  \\\"amount\\\": 45,\\n  \\\"currency\\\": \\\"EUR\\\",\\n  \\\"authorizedByShopper\\\": true,\\n  \\\"payerInfo\\\": {\\n    \\\"firstName\\\": \\\"John\\\",\\n    \\\"lastName\\\": \\\"Doe\\\",\\n    \\\"zip\\\": \\\"12345\\\",\\n    \\\"country\\\": \\\"fr\\\"\\n  },\\n  \\\"paymentSource\\\": {\\n    \\\"sepaDirectDebitInfo\\\": {\\n      \\\"sepaDirectDebit\\\": {\\n        \\\"iban\\\": \\\"DE09100100101234567893\\\"\\n      }\\n    }\\n  }\\n}'\",\n      \"language\": \"curl\",\n      \"name\": \"with SEPA Direct Debit\"\n    }\n  ]\n}\n[/block]\n###Response Examples\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"chargeId\\\": 12948563,\\n  \\\"subscriptionId\\\": 10542433,\\n  \\\"vaultedShopperId\\\": 22193703,\\n  \\\"transactionId\\\": \\\"1015009255\\\",\\n  \\\"transactionDate\\\": \\\"2017-10-31\\\",\\n  \\\"amount\\\": 45,\\n  \\\"currency\\\": \\\"USD\\\",\\n  \\\"softDescriptor\\\": \\\"BLS&#x2a;default_descriptor\\\",\\n  \\\"paymentSource\\\": {\\n    \\\"creditCardInfo\\\": {\\n      \\\"creditCard\\\": {\\n        \\\"cardLastFourDigits\\\": \\\"0026\\\",\\n        \\\"cardType\\\": \\\"VISA\\\",\\n        \\\"cardSubType\\\": \\\"CREDIT\\\",\\n        \\\"cardCategory\\\": \\\"CLASSIC\\\",\\n        \\\"expirationMonth\\\": \\\"05\\\",\\n        \\\"expirationYear\\\": \\\"2018\\\"\\n      }\\n    }\\n  },\\n  \\\"chargeInfo\\\": {\\n    \\\"chargeType\\\": \\\"INITIAL\\\"\\n  },\\n  \\\"processingInfo\\\": {\\n    \\\"processingStatus\\\": \\\"SUCCESS\\\"\\n  }\\n}\",\n      \"language\": \"json\",\n      \"name\": \"Create Merchant-Managed Subscription response: with credit card\"\n    },\n    {\n      \"code\": \"{\\n  \\\"chargeId\\\": \\\"165323\\\",\\n  \\\"subscriptionId\\\": 39518448,\\n  \\\"vaultedShopperId\\\": 19559630,\\n  \\\"transactionId\\\": \\\"38492608\\\",\\n  \\\"transactionDate\\\": \\\"2017-10-13\\\",\\n  \\\"amount\\\": 45,\\n  \\\"currency\\\": \\\"USD\\\",\\n  \\\"softDescriptor\\\": \\\"BLS*Testing\\\",\\n  \\\"paymentSource\\\": {\\n    \\\"wallet\\\": {\\n      \\\"billingContactInfo\\\": {\\n        \\\"firstName\\\": \\\"Jane\\\",\\n        \\\"lastName\\\": \\\"Shopper\\\",\\n        \\\"address1\\\": \\\"800 South St\\\",\\n        \\\"city\\\": \\\"Waltham\\\",\\n        \\\"zip\\\": \\\"02453\\\",\\n        \\\"country\\\": \\\"us\\\"\\n      },\\n      \\\"applePay\\\": {\\n        \\\"cardLastFourDigits\\\": \\\"0492\\\",\\n        \\\"cardType\\\": \\\"VISA\\\",\\n        \\\"cardSubType\\\": \\\"DEBIT\\\",\\n        \\\"dpanLastFourDigits\\\": \\\"6889\\\",\\n        \\\"dpanExpirationMonth\\\": \\\"11\\\",\\n        \\\"dpanExpirationYear\\\": \\\"2025\\\"\\n      }\\n    }\\n  },\\n  \\\"chargeInfo\\\": {\\n    \\\"chargeType\\\": \\\"INITIAL\\\"\\n  }\\n}\",\n      \"language\": \"json\",\n      \"name\": \"with Apple Pay\"\n    },\n    {\n      \"code\": \"{\\n  \\\"vaultedShopperId\\\": 22193707,\\n  \\\"transactionId\\\": \\\"1015009259\\\",\\n  \\\"transactionDate\\\": \\\"2017-10-31\\\",\\n  \\\"amount\\\": 45,\\n  \\\"currency\\\": \\\"EUR\\\",\\n  \\\"softDescriptor\\\": \\\"default_descriptor\\\",\\n  \\\"paymentSource\\\": {\\n    \\\"sepaDirectDebitInfo\\\": {\\n      \\\"sepaDirectDebit\\\": {\\n        \\\"ibanFirstFour\\\": \\\"DE09\\\",\\n        \\\"ibanLastFour\\\": \\\"7893\\\",\\n        \\\"mandateId\\\": \\\"Blu153577\\\",\\n        \\\"mandateDate\\\": \\\"31-Oct-17\\\",\\n        \\\"preNotificationText\\\": \\\"The amount of 45 EUR will be collected using SEPA Direct Debit with Mandate Blu153577 from your bank account IBAN DE09XXXXXX7893 in the next few days. Please ensure sufficient funds in your account.\\\",\\n        \\\"preNotificationTranslationRef\\\": \\\"https://sandbox.bluesnap.com/services/2/translations/sepa/prenotification?transactionid=1015009259\\\"\\n      }\\n    }\\n  },\\n  \\\"chargeInfo\\\": {\\n    \\\"chargeType\\\": \\\"INITIAL\\\"\\n  },\\n  \\\"processingInfo\\\": {\\n    \\\"processingStatus\\\": \\\"PENDING\\\"\\n  }\\n}\",\n      \"language\": \"json\",\n      \"name\": \"with SEPA Direct Debit\"\n    }\n  ]\n}\n[/block]\n<a class=\"btn btn-primary\" href=\"#\" role=\"button\">Back to Top</a>\n\n<hr>\n\n##Example Descriptions\n\n###Create Merchant-Managed Subscription: with credit card\nThis example shows a Create Merchant-Managed Subscription request with a credit card and a new shopper, with details about the shopper and their payment method. \n\n###Create Merchant-Managed Subscription: with Apple Pay\nThis example shows a Create Merchant-Managed Subscription request with an Apple Pay wallet. In the request, include `encodedPaymentToken` inside `paymentSource` > `wallet` > `applePay`. See the [Apple Pay Guide](/v1.0/docs/apple-pay#section-implementing-apple-pay-in-your-website-or-ios-app) for more information.\n\n**Note**: To test Apple Pay, follow the steps in the [Apple Pay Guide](/v1.0/docs/apple-pay#section-implementing-apple-pay-in-your-website-or-ios-app). The API Explorer does not support Apple Pay testing. \n\n###Create Merchant-Managed Subscription: with SEPA Direct Debit\nThis example shows a Create Merchant-Managed Subscription request with a new shopper with the SEPA Direct Debit payment method. In the request, include `authorizedByShopper` with a value set to **true** to indicate that you've collected the shopper's [mandate acceptance](/v1.0/docs/sepa-direct-debit#section-step-1-collect-a-mandate-acceptance-from-your-shopper).\n\n**Note**: `subscriptionId` will not be returned in the response. The subscription ID will be created when the shopper's account is debited (typically within 5 - 6 business days) and the `processingStatus` value changes to **SUCCESS**. You will be informed of the subscription ID via `Charge` webhook or via [Retrieve Specific Charge](doc:retrieve-specific-charge) request. \n\n<br>\n<a class=\"btn btn-primary\" href=\"#\" role=\"button\">Back to Top</a>\n\n<hr>\n\n##API Explorer\nTo test out a call, enter the JSON portion of the request below and then click **Try it!**\n\n**Tip**: Use the JSON code below as a starting point. You can enter different parameter values to see how your test scenario would work. *The request headers, including authorization, are already built in for you in this test area, so you should not include them here.*\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\n  \\\"amount\\\": 45, \\n  \\\"currency\\\": \\\"USD\\\",\\n  \\\"payerInfo\\\": {\\n    \\\"firstName\\\": \\\"John\\\",\\n    \\\"lastName\\\": \\\"Doe\\\",\\n    \\\"zip\\\": \\\"12345\\\",\\n    \\\"country\\\": \\\"us\\\"\\n  },\\n  \\\"paymentSource\\\": {\\n    \\\"creditCardInfo\\\": {\\n      \\\"creditCard\\\": {\\n        \\\"expirationYear\\\": 2018,\\n        \\\"securityCode\\\": 111,\\n        \\\"expirationMonth\\\": \\\"05\\\",\\n        \\\"cardNumber\\\": 4012000033330026\\n      }\\n    }\\n  }\\n}\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]","excerpt":"","slug":"create-merchant-managed-subscription","type":"endpoint","title":"Create Merchant-Managed Subscription"}

postCreate Merchant-Managed Subscription


Definition

{{ api_url }}{{ page_api_url }}

Documentation

If you manage your own subscriptions, the Create Merchant-Managed Subscription request enables you to set up a merchant-managed subscription, which associates an initial subscription charge with all recurring charges.

To process recurring subscription charges, you'll send a Create Merchant-Managed Subscription Charge request.

See the guide on using merchant-managed subscriptions

For more information on working with merchant-managed subscriptions, see Merchant-Managed Subscriptions.

Try it in the API Explorer

Request Content

charge object    required, contains the following properties (see charge):

      amount decimal    required for SEPA Direct Debit; optional otherwise

      currency string    required

      vaultedShopperId integer    optional - do not include if sending payerInfo

      payerInfo object    optional - do not include if sending vaultedShopperId (see payerInfo)

      paymentSource object    required for payerInfo; optional for vaultedShopperId (see paymentSource)

      softDescriptor string    optional

      descriptorPhoneNumber string    optional

      authorizedByShopper     boolean   required for SEPA Direct Debit   value must be true

      transactionFraudInfo object    optional (see transactionFraudInfo)

Response Details

If successful, the response HTTP status code is 200 OK.
The response body contains the charge resource.
The subscriptionId appears in the response body (unless payment source was SEPA Direct Debit).


Examples

Request Examples

curl -v -X POST https://sandbox.bluesnap.com/services/2/recurring/ondemand \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
  "amount": 45, 
  "currency": "USD",
  "payerInfo": {
    "firstName": "John",
    "lastName": "Doe",
    "zip": "12345",
    "country": "us"
  },
  "paymentSource": {
    "creditCardInfo": {
      "creditCard": {
        "expirationYear": 2018,
        "securityCode": 111,
        "expirationMonth": "05",
        "cardNumber": 4012000033330026
      }
    }
  }
}'
curl -v -X POST https://sandbox.bluesnap.com/services/2/recurring/ondemand \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
  "amount": 45, 
  "currency": "USD", 
  "paymentSource": {
    "wallet": {
      "applePay": {
        "encodedPaymentToken": "eyJ0b2tliZ2l2ZW5OYW1lIjoiTG9kIiwiY291bnRye…"
      }
    }
  }	
}'
curl -v -X POST https://sandbox.bluesnap.com/services/2/recurring/ondemand \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
  "amount": 45,
  "currency": "EUR",
  "authorizedByShopper": true,
  "payerInfo": {
    "firstName": "John",
    "lastName": "Doe",
    "zip": "12345",
    "country": "fr"
  },
  "paymentSource": {
    "sepaDirectDebitInfo": {
      "sepaDirectDebit": {
        "iban": "DE09100100101234567893"
      }
    }
  }
}'

Response Examples

{
  "chargeId": 12948563,
  "subscriptionId": 10542433,
  "vaultedShopperId": 22193703,
  "transactionId": "1015009255",
  "transactionDate": "2017-10-31",
  "amount": 45,
  "currency": "USD",
  "softDescriptor": "BLS&#x2a;default_descriptor",
  "paymentSource": {
    "creditCardInfo": {
      "creditCard": {
        "cardLastFourDigits": "0026",
        "cardType": "VISA",
        "cardSubType": "CREDIT",
        "cardCategory": "CLASSIC",
        "expirationMonth": "05",
        "expirationYear": "2018"
      }
    }
  },
  "chargeInfo": {
    "chargeType": "INITIAL"
  },
  "processingInfo": {
    "processingStatus": "SUCCESS"
  }
}
{
  "chargeId": "165323",
  "subscriptionId": 39518448,
  "vaultedShopperId": 19559630,
  "transactionId": "38492608",
  "transactionDate": "2017-10-13",
  "amount": 45,
  "currency": "USD",
  "softDescriptor": "BLS*Testing",
  "paymentSource": {
    "wallet": {
      "billingContactInfo": {
        "firstName": "Jane",
        "lastName": "Shopper",
        "address1": "800 South St",
        "city": "Waltham",
        "zip": "02453",
        "country": "us"
      },
      "applePay": {
        "cardLastFourDigits": "0492",
        "cardType": "VISA",
        "cardSubType": "DEBIT",
        "dpanLastFourDigits": "6889",
        "dpanExpirationMonth": "11",
        "dpanExpirationYear": "2025"
      }
    }
  },
  "chargeInfo": {
    "chargeType": "INITIAL"
  }
}
{
  "vaultedShopperId": 22193707,
  "transactionId": "1015009259",
  "transactionDate": "2017-10-31",
  "amount": 45,
  "currency": "EUR",
  "softDescriptor": "default_descriptor",
  "paymentSource": {
    "sepaDirectDebitInfo": {
      "sepaDirectDebit": {
        "ibanFirstFour": "DE09",
        "ibanLastFour": "7893",
        "mandateId": "Blu153577",
        "mandateDate": "31-Oct-17",
        "preNotificationText": "The amount of 45 EUR will be collected using SEPA Direct Debit with Mandate Blu153577 from your bank account IBAN DE09XXXXXX7893 in the next few days. Please ensure sufficient funds in your account.",
        "preNotificationTranslationRef": "https://sandbox.bluesnap.com/services/2/translations/sepa/prenotification?transactionid=1015009259"
      }
    }
  },
  "chargeInfo": {
    "chargeType": "INITIAL"
  },
  "processingInfo": {
    "processingStatus": "PENDING"
  }
}

Back to Top


Example Descriptions

Create Merchant-Managed Subscription: with credit card

This example shows a Create Merchant-Managed Subscription request with a credit card and a new shopper, with details about the shopper and their payment method.

Create Merchant-Managed Subscription: with Apple Pay

This example shows a Create Merchant-Managed Subscription request with an Apple Pay wallet. In the request, include encodedPaymentToken inside paymentSource > wallet > applePay. See the Apple Pay Guide for more information.

Note: To test Apple Pay, follow the steps in the Apple Pay Guide. The API Explorer does not support Apple Pay testing.

Create Merchant-Managed Subscription: with SEPA Direct Debit

This example shows a Create Merchant-Managed Subscription request with a new shopper with the SEPA Direct Debit payment method. In the request, include authorizedByShopper with a value set to true to indicate that you've collected the shopper's mandate acceptance.

Note: subscriptionId will not be returned in the response. The subscription ID will be created when the shopper's account is debited (typically within 5 - 6 business days) and the processingStatus value changes to SUCCESS. You will be informed of the subscription ID via Charge webhook or via Retrieve Specific Charge request.



Back to Top


API Explorer

To test out a call, enter the JSON portion of the request below and then click Try it!

Tip: Use the JSON code below as a starting point. You can enter different parameter values to see how your test scenario would work. The request headers, including authorization, are already built in for you in this test area, so you should not include them here.

{
  "amount": 45, 
  "currency": "USD",
  "payerInfo": {
    "firstName": "John",
    "lastName": "Doe",
    "zip": "12345",
    "country": "us"
  },
  "paymentSource": {
    "creditCardInfo": {
      "creditCard": {
        "expirationYear": 2018,
        "securityCode": 111,
        "expirationMonth": "05",
        "cardNumber": 4012000033330026
      }
    }
  }
}

User Information

Try It Out


post
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}