If you manage your own subscriptions, the Create Merchant-Managed Subscription request lets you 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.
For more information on working with merchant-managed subscriptions, refer to Merchant-Managed Subscriptions.
Reporting Benefits
With merchant-managed subscriptions, you get access to our advanced reporting capabilities that provide a clear differentiation between one-time and recurring charges, and our conversion reports that take into account your specific dunning logic.
Send a test request
Go to API Explorer to send a test request to our sandbox environment and receive a response in real time.
Request Content
Send a charge object, with the following:
Property | Type | Required |
---|---|---|
amount | decimal | required for ACH/ECP and SEPA Direct Debit; otherwise optional |
authorizedByShopper | boolean | required for ACH/ECP and SEPA Direct Debit (value must be true) |
currency | string | required |
descriptorPhoneNumber | string | optional |
level3Data | object | optional (refer to level3Data) |
merchantTransactionId | string | optional |
networkTransactionInfo | object | optional (refer to networkTransactionInfo) |
payerInfo | object | optional - do not include if sending vaultedShopperId (refer to payerInfo) |
paymentSource | object | required for payerInfo ; optional for vaultedShopperId (refer to paymentSource) |
softDescriptor | string | optional |
taxReference | string | optional |
threeDSecure | object | optional (refer to threeDSecure) |
transactionFraudInfo | object | optional (refer to transactionFraudInfo) |
scheduled | boolean | optional |
transactionInitiator | string | optional |
transactionMetaData | object | optional (refer to transactionMetaData) |
vaultedShopperId | integer | optional - do not include if sending payerInfo |
vendorsInfo | object | optional (refer to vendorsInfo) |
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 ACH/ECP or 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",
"merchantTransactionId": "MyUniqueOnDemandSubscription",
"taxReference": "048deff0-a285-47e1-bc39-42f79bf0095b",
"payerInfo": {
"firstName": "John",
"lastName": "Doe",
"zip": "02453",
"country": "us"
},
"paymentSource": {
"creditCardInfo": {
"creditCard": {
"expirationYear": 2023,
"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": {
"walletType": "APPLE_PAY",
"encodedPaymentToken": "eyJiaWxsaW5nQ29udGFjdCI6eyJhZGRyZ..."
}
}
}
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": "02453",
"country": "fr"
},
"paymentSource": {
"sepaDirectDebitInfo": {
"sepaDirectDebit": {
"iban": "DE09100100101234567893"
}
}
}
}
curl -v -X POST https://sandbox.bluesnap.com/services/2/recurring/ondemand \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
"amount": 65,
"currency": "USD",
"authorizedByShopper": true,
"payerInfo": {
"firstName": "Jane",
"lastName": "Doe",
"zip": "02453",
"country": "us"
},
"paymentSource": {
"ecpInfo": {
"ecp": {
"accountNumber": 4099999992,
"routingNumber": "011075150",
"accountType": "CONSUMER_CHECKING"
}
}
}
}
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": {
"walletType": "GOOGLE_PAY",
"encodedPaymentToken": "eyJ0b2tliZ2l2ZW5OYW1lIjoiTG9kIiwiY291bnRye…"
}
}
}
curl -v -X POST https://sandbox.bluesnap.com/services/2/recurring/ondemand \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
"payerInfo":{
"firstName":"PIFirstName",
"lastName":"PILastName",
"zip":"PIZip",
"email":"[email protected]",
"country":"il",
"address":"PIaddress1",
"address2":"PIaddress2",
"city":"PICity"
},
"paymentSource":{
"creditCardInfo":{
"creditCard":{
"cardNumber":"5555555555554444",
"securityCode":"111",
"cardType":"MASTERCARD",
"expirationMonth":"07",
"expirationYear":"2025"
},
"billingContactInfo":{
"firstName":"BiFirstName",
"lastName":"BiLastName",
"address1":"BiAddress1",
"address2":"BiAddress2",
"city":"BiCity",
"state":"CA",
"country":"us",
"zip":"BiZip"
}
}
},
"amount":"10",
"currency":"USD"
}
curl -v -X POST https://sandbox.bluesnap.com/services/2/recurring/ondemand \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
"vaultedShopperId":19641554,
"paymentSource":{
"creditCardInfo":{
"creditCard":{
"cardNumber":"5555555555554444",
"securityCode":"111",
"cardType":"MASTERCARD",
"expirationMonth":"07",
"expirationYear":"2025"
},
"billingContactInfo":{
"firstName":"BiFirstName",
"lastName":"BiLastName",
"address1":"BiAddress1",
"address2":"BiAddress2",
"city":"BiCity",
"state":"CA",
"country":"us",
"zip":"BiZip"
}
}
},
"amount":"10",
"currency":"USD"
}
curl -v -X POST https://sandbox.bluesnap.com/services/2/recurring/ondemand \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
"payerInfo":{
"firstName":"PIFirstName",
"lastName":"PILastName",
"zip":"PIZip",
"email":"[email protected]",
"country":"il",
"address":"PIaddress1",
"address2":"PIaddress2",
"city":"PICity"
},
"paymentSource":{
"creditCardInfo":{
"pfToken":"77fdabea752d7a23c763d3690111ffea9d173b34eaa4e8e37d7c59360a167d4a_",
"billingContactInfo":{
"firstName":"BiFirstName",
"lastName":"BiLastName",
"address1":"BiAddress1",
"address2":"BiAddress2",
"city":"BiCity",
"state":"CA",
"country":"us",
"zip":"BiZip"
}
}
},
"amount":"10",
"currency":"USD"
}
curl -v -X POST https://sandbox.bluesnap.com/services/2/recurring/ondemand \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
"vaultedShopperId":19641542,
"paymentSource":{
"creditCardInfo":{
"pfToken":"2f1fee480db183617a5e79b340fb2b20954331d6c96b4889a846f95546ef8fc1_",
"billingContactInfo":{
"firstName":"BiFirstName",
"lastName":"BiLastName",
"address1":"BiAddress1",
"address2":"BiAddress2",
"city":"BiCity",
"state":"CA",
"country":"us",
"zip":"BiZip"
}
}
},
"amount":"10",
"currency":"USD"
}
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",
"merchantTransactionId": "MyUniqueOnDemandSubscription",
"payerInfo": {
"firstName": "John",
"lastName": "Doe",
"zip": "02453",
"country": "us"
},
"paymentSource": {
"creditCardInfo": {
"creditCard": {
"expirationYear": 2023,
"securityCode": 111,
"expirationMonth": "05",
"cardNumber": 4012000033330026
}
}
},
"vendorsInfo": {
"vendorInfo": [{ "vendorId": "10398032" }]
}
}'
curl -v -X POST https://sandbox.bluesnap.com/services/2/recurring/ondemand \
-H 'Content-Type: application/json' \
-H 'Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=' \
-d '
{
"amount": 100,
"currency": "USD",
"merchantTransactionId": "112222",
"transactionMetaData": {
"metaData": [
{
"metaValue": 20,
"metaKey": "stateTaxAmount",
"metaDescription": "State Tax Amount"
},
{
"metaValue": 20,
"metaKey": "cityTaxAmount",
"metaDescription": "City Tax Amount"
},
{
"metaValue": 10,
"metaKey": "shippingAmount",
"metaDescription": "Shipping Amount"
}
]
},
"payerInfo": {
"firstName": "John",
"lastName": "Doe",
"zip": "92614",
"country": "us"
},
"paymentSource": {
"creditCardInfo": {
"creditCard": {
"expirationYear": 2023,
"securityCode": 111,
"expirationMonth": "05",
"cardNumber": 4111111111111111
}
}
}
}'
Response Examples
{
"chargeId": 14837941,
"subscriptionId": 13823081,
"vaultedShopperId": 23976843,
"transactionId": "1020296963",
"merchantTransactionId": "MyUniqueOnDemandSubscription",
"taxReference": "048deff0-a285-47e1-bc39-42f79bf0095b",
"transactionDate": "2019-03-14",
"amount": 45,
"currency": "USD",
"softDescriptor": "BLS*Testing",
"paymentSource": {
"creditCardInfo": {
"billingContactInfo": {
"firstName": "John",
"lastName": "Doe",
"zip": "02453",
"country": "us"
},
"creditCard": {
"cardLastFourDigits": "0026",
"cardType": "VISA",
"cardSubType": "CREDIT",
"cardCategory": "CLASSIC",
"binCategory": "CONSUMER",
"cardRegulated": "N",
"issuingBank": "EXTRAS TEST - VISA",
"expirationMonth": "05",
"expirationYear": "2023",
"issuingCountryCode": "ru"
}
}
},
"chargeInfo": {
"chargeType": "INITIAL"
},
"processingInfo": {
"processingStatus": "SUCCESS",
"transactionRegion": "US"
},
"fraudResultInfo": {
"deviceDataCollector": "N"
}
}
{
"chargeId": 175047,
"subscriptionId": 39555006,
"vaultedShopperId": 19598228,
"transactionId": "38599972",
"transactionDate": "2021-09-16",
"amount": 45.00,
"currency": "USD",
"softDescriptor": "BLS*CodeDiggers",
"paymentSource": {
"wallet": {
"walletType": "APPLE_PAY",
"billingContactInfo": {
"firstName": "John",
"lastName": "Smith",
"address1": "800 South Street",
"city": "Waltham",
"state": "MA",
"zip": "01822",
"country": "us"
},
"applePay": {
"cardLastFourDigits": "1471",
"cardType": "MASTERCARD",
"cardSubType": "DEBIT",
"cardCategory": "ACQUIRER ONLY",
"binCategory": "CONSUMER",
"cardRegulated": "N",
"issuingCountryCode": "us",
"issuingBank": "MASTERCARD - MEMBER TEST FACILITY",
"dpanLastFourDigits": "6937",
"dpanExpirationMonth": "9",
"dpanExpirationYear": "2022"
},
"tokenizedCard": {
"dpanExpirationMonth": "9",
"dpanExpirationYear": "2022",
"dpanLastFourDigits": "6937",
"cardLastFourDigits": "1471",
"cardType": "MASTERCARD",
"cardSubType": "DEBIT",
"cardCategory": "ACQUIRER ONLY",
"binCategory": "CONSUMER",
"cardRegulated": "N",
"issuingCountryCode": "us",
"issuingBank": "MASTERCARD - MEMBER TEST FACILITY"
}
}
},
"chargeInfo": {
"chargeType": "INITIAL"
},
"processingInfo": {
"processingStatus": "SUCCESS",
"authorizationCode": "732032"
},
"fraudResultInfo": {}
}
{
"vaultedShopperId": 22193707,
"transactionId": "1015009259",
"transactionDate": "2017-10-31",
"amount": 45,
"currency": "EUR",
"softDescriptor": "BLS*Testing",
"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"
}
}
{
"vaultedShopperId": 22330225,
"transactionId": "1015609477",
"transactionDate": "2018-01-25",
"amount": 65,
"currency": "USD",
"softDescriptor": "BLS*Testing",
"paymentSource": {
"ecpInfo": {
"ecp": {
"accountNumber": "4099999992",
"routingNumber": "011075150",
"accountType": "CONSUMER_CHECKING"
}
}
},
"chargeInfo": {
"chargeType": "INITIAL"
},
"processingInfo": {
"processingStatus": "PENDING"
}
}
{
"subscriptionId": 39555006,
"vaultedShopperId": 19639434,
"transactionId": "38593756",
"transactionDate": "2018-11-12",
"amount": 45,
"currency": "USD",
"softDescriptor": "BLS*Testing",
"paymentSource": {
"wallet": {
"walletType": "GOOGLE_PAY",
"billingContactInfo": {
"firstName": "Susan",
"lastName": "madden",
"address1": "351 Eliot Street",
"city": "Milton",
"state": "MA",
"zip": "02186",
"country": "us"
},
"tokenizedCard": {
"cardLastFourDigits": "7971",
"cardType": "VISA",
"cardSubType": "CREDIT",
"dpanExpirationMonth": "9",
"dpanExpirationYear": "2025",
"dpanLastFourDigits": "2041"
}
}
},
"chargeInfo": {
"chargeType": "INITIAL"
},
"processingInfo": {
"processingStatus": "SUCCESS"
}
}
{
"subscriptionId": 39555006,
"vaultedShopperId": 19639432,
"transactionId": "38593754",
"transactionDate": "2018-11-12",
"amount": 45,
"currency": "USD",
"softDescriptor": "BLS*Testing",
"paymentSource": {
"creditCardInfo": {
"creditCard": {
"cardLastFourDigits": "1111",
"cardType": "VISA",
"binCategory": "CONSUMER",
"expirationMonth": "12",
"expirationYear": "2023"
}
}
},
"chargeInfo": {
"chargeType": "INITIAL"
},
"processingInfo": {
"processingStatus": "SUCCESS"
}
}
{
"chargeId":251307,
"subscriptionId":39598858,
"vaultedShopperId":19641864,
"transactionId":"38597362",
"transactionDate":"2019-01-27",
"amount":10.00,
"currency":"USD",
"softDescriptor":"BLS*Testing",
"paymentSource":{
"creditCardInfo":{
"billingContactInfo":{
"firstName":"BiFirstName",
"lastName":"BiLastName",
"address1":"BiAddress1",
"address2":"BiAddress2",
"city":"BiCity",
"state":"CA",
"zip":"BiZip",
"country":"us"
},
"creditCard":{
"cardLastFourDigits":"4444",
"cardType":"MASTERCARD",
"binCategory":"CONSUMER",
"expirationMonth":"07",
"expirationYear":"2025"
}
}
},
"chargeInfo":{
"chargeType":"INITIAL"
},
"processingInfo":{
"processingStatus":"SUCCESS"
},
"fraudResultInfo":{
"deviceDataCollector":"N"
}
}
{
"chargeId":251323,
"subscriptionId":39598874,
"vaultedShopperId":19641880,
"transactionId":"38597386",
"transactionDate":"2019-01-27",
"amount":10.00,
"currency":"USD",
"softDescriptor":"BLS*Testing",
"paymentSource":{
"creditCardInfo":{
"billingContactInfo":{
"firstName":"BiFirstName",
"lastName":"BiLastName",
"address1":"BiAddress1",
"address2":"BiAddress2",
"city":"BiCity",
"state":"CA",
"zip":"BiZip",
"country":"us"
},
"creditCard":{
"cardLastFourDigits":"4444",
"cardType":"MASTERCARD",
"binCategory":"CONSUMER",
"expirationMonth":"07",
"expirationYear":"2025"
}
}
},
"chargeInfo":{
"chargeType":"INITIAL"
},
"processingInfo":{
"processingStatus":"SUCCESS"
},
"fraudResultInfo":{
"deviceDataCollector":"N"
}
}
{
"chargeId":251317,
"subscriptionId":39598868,
"vaultedShopperId":19641874,
"transactionId":"38597376",
"transactionDate":"2019-01-27",
"amount":10.00,
"currency":"USD",
"softDescriptor":"BLS*Testing",
"paymentSource":{
"creditCardInfo":{
"billingContactInfo":{
"firstName":"BiFirstName",
"lastName":"BiLastName",
"address1":"BiAddress1",
"address2":"BiAddress2",
"city":"BiCity",
"state":"CA",
"zip":"BiZip",
"country":"us"
},
"creditCard":{
"cardLastFourDigits":"0005",
"cardType":"AMEX",
"binCategory":"CONSUMER",
"expirationMonth":"11",
"expirationYear":"2024"
}
}
},
"chargeInfo":{
"chargeType":"INITIAL"
},
"processingInfo":{
"processingStatus":"SUCCESS"
},
"fraudResultInfo":{
"deviceDataCollector":"N"
}
}
{
"chargeId":251311,
"subscriptionId":39598862,
"vaultedShopperId":19641868,
"transactionId":"38597370",
"transactionDate":"2019-01-27",
"amount":10.00,
"currency":"USD",
"softDescriptor":"BLS*Testing",
"paymentSource":{
"creditCardInfo":{
"billingContactInfo":{
"firstName":"BiFirstName",
"lastName":"BiLastName",
"address1":"BiAddress1",
"address2":"BiAddress2",
"city":"BiCity",
"state":"CA",
"zip":"BiZip",
"country":"us"
},
"creditCard":{
"cardLastFourDigits":"0005",
"cardType":"AMEX",
"binCategory":"CONSUMER",
"expirationMonth":"11",
"expirationYear":"2024"
}
}
},
"chargeInfo":{
"chargeType":"INITIAL"
},
"processingInfo":{
"processingStatus":"SUCCESS"
},
"fraudResultInfo":{
"deviceDataCollector":"N"
}
}
{
"chargeId": 14837941,
"subscriptionId": 13823081,
"vaultedShopperId": 23976843,
"transactionId": "1020296963",
"merchantTransactionId": "MyUniqueOnDemandSubscription",
"transactionDate": "2019-03-14",
"amount": 45,
"currency": "USD",
"softDescriptor": "BLS*Testing",
"paymentSource": {
"creditCardInfo": {
"billingContactInfo": {
"firstName": "John",
"lastName": "Doe",
"zip": "02453",
"country": "us"
},
"creditCard": {
"cardLastFourDigits": "0026",
"cardType": "VISA",
"cardSubType": "CREDIT",
"cardCategory": "CLASSIC",
"binCategory": "CONSUMER",
"cardRegulated": "N",
"issuingBank": "EXTRAS TEST - VISA",
"expirationMonth": "05",
"expirationYear": "2023",
"issuingCountryCode": "ru"
}
}
},
"chargeInfo": {
"chargeType": "INITIAL"
},
"processingInfo": {
"processingStatus": "SUCCESS",
"authorizationCode": "654321"
},
"fraudResultInfo": {
"deviceDataCollector": "N"
}
}
{
"chargeId": 18319053,
"subscriptionId": 19752665,
"vaultedShopperId": 27568045,
"transactionId": "1031082689",
"merchantTransactionId": "MyUniqueOnDemandSubscription",
"transactionDate": "2020-05-26",
"amount": 45.0,
"currency": "USD",
"softDescriptor": "BLS*default_descriptor",
"paymentSource": {
"creditCardInfo": {
"billingContactInfo": {
"firstName": "John",
"lastName": "Doe",
"zip": "02453",
"country": "us"
},
"creditCard": {
"cardLastFourDigits": "0026",
"cardType": "VISA",
"cardSubType": "CREDIT",
"cardCategory": "CLASSIC",
"binCategory": "CONSUMER",
"cardRegulated": "N",
"issuingBank": "EXTRAS TEST - VISA",
"expirationMonth": "05",
"expirationYear": "2023",
"issuingCountryCode": "ru"
}
}
},
"chargeInfo": {
"chargeType": "INITIAL"
},
"processingInfo": {
"processingStatus": "SUCCESS",
"authorizationCode": "654321"
},
"vendorsInfo": {
"vendorInfo": [
{
"vendorId": 10398032,
"commissionPercent": 90.2
}
]
},
"fraudResultInfo": {}
}
{
"chargeId": 20400685,
"subscriptionId": 23451699,
"vaultedShopperId": 29970021,
"transactionId": "1039090759",
"merchantTransactionId": "112222",
"transactionDate": "2020-12-28",
"amount": 100,
"currency": "USD",
"softDescriptor": "BLS*default_descriptor",
"paymentSource": {
"creditCardInfo": {
"billingContactInfo": {
"firstName": "John",
"lastName": "Doe",
"zip": "92614",
"country": "us"
},
"creditCard": {
"cardLastFourDigits": "1111",
"cardType": "VISA",
"cardSubType": "CREDIT",
"binCategory": "CONSUMER",
"cardRegulated": "Y",
"issuingBank": "JPMORGAN CHASE BANK, N.A.",
"expirationMonth": "05",
"expirationYear": "2023",
"issuingCountryCode": "us"
}
}
},
"chargeInfo": {
"chargeType": "INITIAL"
},
"processingInfo": {
"processingStatus": "SUCCESS",
"authorizationCode": "654321"
},
"fraudResultInfo": {}
}
API Explorer
BlueSnap provides a sandbox environment so you can test basic requests with this endpoint. You can view the request in the API Explorer console and its response directly below the console.
The console includes a sample request with predefined parameter values. To send a request with custom values, edit the parameter fields below. As you edit the fields, your custom values display in the request in the console.
Click the Try it! button below the request example when you are ready to send your request.