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.
Tip
You can test out a request that hits our sandbox in real-time. Follow the instructions here to use the "Try It!" feature on the right side.
Request Content
Property | Type | Required |
---|---|---|
charge | object | required, contains the properties below (refer to charge) |
amount | decimal | required for ACH/ECP and SEPA Direct Debit; otherwise optional |
currency | string | required |
vendorsInfo | object | optional (refer to vendorsInfo) |
vaultedShopperId | integer | optional - do not include if sending payerInfo |
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 |
descriptorPhoneNumber | string | optional |
authorizedByShopper | boolean | required for ACH/ECP and SEPA Direct Debit (value must be true) |
threeDSecure | object | optional (refer to threeDSecure) |
transactionFraudInfo | object | optional (refer to transactionFraudInfo) |
transactionMetaData | object | optional (refer to transactionMetaData) |
level3Data | object | optional (refer to level3Data) |
scheduled | boolean | optional |
merchantTransactionId | string | optional |
taxReference | string | optional |
networkTransactionInfo | object | optional (refer to networkTransactionInfo) |
transactionInitiator | string | optional |
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"
},
"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
To test out a basic API request, click the "Try It!" button in the right-hand column to test using the default, pre-populated sample values. To test with your own values, edit the parameter fields below. You'll see them populate in the right-hand column and you can click the "Try It!" button to submit your test request and see a response.