Enroll a customer in card-on-file recurring debits
curl --request POST \
--url https://api.example.com/subscription-intents \
--header 'ApiKey: <apikey>' \
--header 'Content-Type: application/json' \
--header 'Environment: <environment>' \
--header 'MerchantId: <merchantid>' \
--data '
{
"customerReference": "cust_01924059",
"email": "customer@example.com",
"currency": "XOF",
"consent": {
"given": true,
"timestamp": "2026-07-03T10:00:00.000Z",
"reference": "consent-01924059"
},
"amount": 5000,
"frequency": "monthly",
"startDate": "2026-08-01",
"billingMode": "rbs_scheduled",
"onSuccessRedirectionUrl": "<string>",
"onFailedRedirectionUrl": "<string>"
}
'import requests
url = "https://api.example.com/subscription-intents"
payload = {
"customerReference": "cust_01924059",
"email": "customer@example.com",
"currency": "XOF",
"consent": {
"given": True,
"timestamp": "2026-07-03T10:00:00.000Z",
"reference": "consent-01924059"
},
"amount": 5000,
"frequency": "monthly",
"startDate": "2026-08-01",
"billingMode": "rbs_scheduled",
"onSuccessRedirectionUrl": "<string>",
"onFailedRedirectionUrl": "<string>"
}
headers = {
"ApiKey": "<apikey>",
"MerchantId": "<merchantid>",
"Environment": "<environment>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
ApiKey: '<apikey>',
MerchantId: '<merchantid>',
Environment: '<environment>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
customerReference: 'cust_01924059',
email: 'customer@example.com',
currency: 'XOF',
consent: {
given: true,
timestamp: '2026-07-03T10:00:00.000Z',
reference: 'consent-01924059'
},
amount: 5000,
frequency: 'monthly',
startDate: '2026-08-01',
billingMode: 'rbs_scheduled',
onSuccessRedirectionUrl: '<string>',
onFailedRedirectionUrl: '<string>'
})
};
fetch('https://api.example.com/subscription-intents', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/subscription-intents",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'customerReference' => 'cust_01924059',
'email' => 'customer@example.com',
'currency' => 'XOF',
'consent' => [
'given' => true,
'timestamp' => '2026-07-03T10:00:00.000Z',
'reference' => 'consent-01924059'
],
'amount' => 5000,
'frequency' => 'monthly',
'startDate' => '2026-08-01',
'billingMode' => 'rbs_scheduled',
'onSuccessRedirectionUrl' => '<string>',
'onFailedRedirectionUrl' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"ApiKey: <apikey>",
"Content-Type: application/json",
"Environment: <environment>",
"MerchantId: <merchantid>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/subscription-intents"
payload := strings.NewReader("{\n \"customerReference\": \"cust_01924059\",\n \"email\": \"customer@example.com\",\n \"currency\": \"XOF\",\n \"consent\": {\n \"given\": true,\n \"timestamp\": \"2026-07-03T10:00:00.000Z\",\n \"reference\": \"consent-01924059\"\n },\n \"amount\": 5000,\n \"frequency\": \"monthly\",\n \"startDate\": \"2026-08-01\",\n \"billingMode\": \"rbs_scheduled\",\n \"onSuccessRedirectionUrl\": \"<string>\",\n \"onFailedRedirectionUrl\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("ApiKey", "<apikey>")
req.Header.Add("MerchantId", "<merchantid>")
req.Header.Add("Environment", "<environment>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/subscription-intents")
.header("ApiKey", "<apikey>")
.header("MerchantId", "<merchantid>")
.header("Environment", "<environment>")
.header("Content-Type", "application/json")
.body("{\n \"customerReference\": \"cust_01924059\",\n \"email\": \"customer@example.com\",\n \"currency\": \"XOF\",\n \"consent\": {\n \"given\": true,\n \"timestamp\": \"2026-07-03T10:00:00.000Z\",\n \"reference\": \"consent-01924059\"\n },\n \"amount\": 5000,\n \"frequency\": \"monthly\",\n \"startDate\": \"2026-08-01\",\n \"billingMode\": \"rbs_scheduled\",\n \"onSuccessRedirectionUrl\": \"<string>\",\n \"onFailedRedirectionUrl\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/subscription-intents")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["ApiKey"] = '<apikey>'
request["MerchantId"] = '<merchantid>'
request["Environment"] = '<environment>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"customerReference\": \"cust_01924059\",\n \"email\": \"customer@example.com\",\n \"currency\": \"XOF\",\n \"consent\": {\n \"given\": true,\n \"timestamp\": \"2026-07-03T10:00:00.000Z\",\n \"reference\": \"consent-01924059\"\n },\n \"amount\": 5000,\n \"frequency\": \"monthly\",\n \"startDate\": \"2026-08-01\",\n \"billingMode\": \"rbs_scheduled\",\n \"onSuccessRedirectionUrl\": \"<string>\",\n \"onFailedRedirectionUrl\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"paymentId": "<string>",
"status": "successful",
"action": {
"type": "ussd",
"message": "<string>",
"data": {
"url": "<string>",
"urls": "<string>",
"method": "post",
"headers": {},
"data": {}
}
}
}{
"status": 400,
"code": "wrong_provider",
"message": "Provider 'unknown_provider' does not exist for country 'CI' and method 'mobile_money'.",
"request_id": "<string>"
}{
"status": 401,
"error": {
"type": "authorization_error",
"code": "wrong_credentials",
"message": "L'ID marchand et/ou la clé d'API sont incorrects."
}
}{
"httpStatus": 409,
"type": "invalid_request",
"code": "unsupported_action",
"message": "This action is not supported"
}{
"status": 429,
"error": "ThrottlerException: Too Many Requests"
}{
"type": "internal_error",
"code": [
"internal_error",
"wrong_credentials",
"not_granted",
"live_mode_not_granted"
],
"message": "An error occurred on our system. Please try again later."
}{
"status": 503,
"code": "merchant_group_unavailable",
"message": "Your merchant group could not be verified. Please retry in a few moments.",
"request_id": "<string>"
}Subscriptions
Enroll a customer in card-on-file recurring debits
Starts a card-on-file enrollment and returns the enrollment payment with the action the customer must complete. Poll its outcome with GET /subscription-intents//status.
POST
/
subscription-intents
Enroll a customer in card-on-file recurring debits
curl --request POST \
--url https://api.example.com/subscription-intents \
--header 'ApiKey: <apikey>' \
--header 'Content-Type: application/json' \
--header 'Environment: <environment>' \
--header 'MerchantId: <merchantid>' \
--data '
{
"customerReference": "cust_01924059",
"email": "customer@example.com",
"currency": "XOF",
"consent": {
"given": true,
"timestamp": "2026-07-03T10:00:00.000Z",
"reference": "consent-01924059"
},
"amount": 5000,
"frequency": "monthly",
"startDate": "2026-08-01",
"billingMode": "rbs_scheduled",
"onSuccessRedirectionUrl": "<string>",
"onFailedRedirectionUrl": "<string>"
}
'import requests
url = "https://api.example.com/subscription-intents"
payload = {
"customerReference": "cust_01924059",
"email": "customer@example.com",
"currency": "XOF",
"consent": {
"given": True,
"timestamp": "2026-07-03T10:00:00.000Z",
"reference": "consent-01924059"
},
"amount": 5000,
"frequency": "monthly",
"startDate": "2026-08-01",
"billingMode": "rbs_scheduled",
"onSuccessRedirectionUrl": "<string>",
"onFailedRedirectionUrl": "<string>"
}
headers = {
"ApiKey": "<apikey>",
"MerchantId": "<merchantid>",
"Environment": "<environment>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
ApiKey: '<apikey>',
MerchantId: '<merchantid>',
Environment: '<environment>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
customerReference: 'cust_01924059',
email: 'customer@example.com',
currency: 'XOF',
consent: {
given: true,
timestamp: '2026-07-03T10:00:00.000Z',
reference: 'consent-01924059'
},
amount: 5000,
frequency: 'monthly',
startDate: '2026-08-01',
billingMode: 'rbs_scheduled',
onSuccessRedirectionUrl: '<string>',
onFailedRedirectionUrl: '<string>'
})
};
fetch('https://api.example.com/subscription-intents', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/subscription-intents",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'customerReference' => 'cust_01924059',
'email' => 'customer@example.com',
'currency' => 'XOF',
'consent' => [
'given' => true,
'timestamp' => '2026-07-03T10:00:00.000Z',
'reference' => 'consent-01924059'
],
'amount' => 5000,
'frequency' => 'monthly',
'startDate' => '2026-08-01',
'billingMode' => 'rbs_scheduled',
'onSuccessRedirectionUrl' => '<string>',
'onFailedRedirectionUrl' => '<string>'
]),
CURLOPT_HTTPHEADER => [
"ApiKey: <apikey>",
"Content-Type: application/json",
"Environment: <environment>",
"MerchantId: <merchantid>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/subscription-intents"
payload := strings.NewReader("{\n \"customerReference\": \"cust_01924059\",\n \"email\": \"customer@example.com\",\n \"currency\": \"XOF\",\n \"consent\": {\n \"given\": true,\n \"timestamp\": \"2026-07-03T10:00:00.000Z\",\n \"reference\": \"consent-01924059\"\n },\n \"amount\": 5000,\n \"frequency\": \"monthly\",\n \"startDate\": \"2026-08-01\",\n \"billingMode\": \"rbs_scheduled\",\n \"onSuccessRedirectionUrl\": \"<string>\",\n \"onFailedRedirectionUrl\": \"<string>\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("ApiKey", "<apikey>")
req.Header.Add("MerchantId", "<merchantid>")
req.Header.Add("Environment", "<environment>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/subscription-intents")
.header("ApiKey", "<apikey>")
.header("MerchantId", "<merchantid>")
.header("Environment", "<environment>")
.header("Content-Type", "application/json")
.body("{\n \"customerReference\": \"cust_01924059\",\n \"email\": \"customer@example.com\",\n \"currency\": \"XOF\",\n \"consent\": {\n \"given\": true,\n \"timestamp\": \"2026-07-03T10:00:00.000Z\",\n \"reference\": \"consent-01924059\"\n },\n \"amount\": 5000,\n \"frequency\": \"monthly\",\n \"startDate\": \"2026-08-01\",\n \"billingMode\": \"rbs_scheduled\",\n \"onSuccessRedirectionUrl\": \"<string>\",\n \"onFailedRedirectionUrl\": \"<string>\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/subscription-intents")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["ApiKey"] = '<apikey>'
request["MerchantId"] = '<merchantid>'
request["Environment"] = '<environment>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"customerReference\": \"cust_01924059\",\n \"email\": \"customer@example.com\",\n \"currency\": \"XOF\",\n \"consent\": {\n \"given\": true,\n \"timestamp\": \"2026-07-03T10:00:00.000Z\",\n \"reference\": \"consent-01924059\"\n },\n \"amount\": 5000,\n \"frequency\": \"monthly\",\n \"startDate\": \"2026-08-01\",\n \"billingMode\": \"rbs_scheduled\",\n \"onSuccessRedirectionUrl\": \"<string>\",\n \"onFailedRedirectionUrl\": \"<string>\"\n}"
response = http.request(request)
puts response.read_body{
"paymentId": "<string>",
"status": "successful",
"action": {
"type": "ussd",
"message": "<string>",
"data": {
"url": "<string>",
"urls": "<string>",
"method": "post",
"headers": {},
"data": {}
}
}
}{
"status": 400,
"code": "wrong_provider",
"message": "Provider 'unknown_provider' does not exist for country 'CI' and method 'mobile_money'.",
"request_id": "<string>"
}{
"status": 401,
"error": {
"type": "authorization_error",
"code": "wrong_credentials",
"message": "L'ID marchand et/ou la clé d'API sont incorrects."
}
}{
"httpStatus": 409,
"type": "invalid_request",
"code": "unsupported_action",
"message": "This action is not supported"
}{
"status": 429,
"error": "ThrottlerException: Too Many Requests"
}{
"type": "internal_error",
"code": [
"internal_error",
"wrong_credentials",
"not_granted",
"live_mode_not_granted"
],
"message": "An error occurred on our system. Please try again later."
}{
"status": 503,
"code": "merchant_group_unavailable",
"message": "Your merchant group could not be verified. Please retry in a few moments.",
"request_id": "<string>"
}Headers
Your api key. To create a key, please get into our dashboard. If you don't have access to it, please reach the Support team.
Your merchant ID. This information is available in our dashboard. If you don't have access to it, please reach the Support team.
Allow you to choose between the sandbox mode to perform some tests or the live mode for real world transactions.
Available options:
live, sandbox Body
application/json
Your reference for the customer being enrolled in card-on-file.
Maximum string length:
255Example:
"cust_01924059"
Customer email, to which the enrollment and recurring-debit notifications are sent.
Example:
"customer@example.com"
Three-letter ISO currency code.
Example:
"XOF"
Required — per the Visa Stored Credential Framework, no card-on-file enrollment can start without an explicit, timestamped consent. Absent or invalid consent causes the enrollment to be rejected.
Show child attributes
Show child attributes
For a rbs_scheduled enrollment: the recurring debit amount, in the smallest currency unit (e.g. 100 cents to charge €1.00) — distinct from any amount charged at enrollment time. For merchant_initiated: not a recurring amount (ignored in live), and in sandbox it selects the simulated enrollment outcome like any enrollment amount would — omit it to simulate success.
Required range:
x <= 9999999999Example:
5000
Recurring debit frequency. Required for a rbs_scheduled enrollment (the default). Not accepted for a merchant_initiated enrollment.
Available options:
weekly, monthly Example:
"monthly"
ISO-8601 date of the first recurring debit. Required for a rbs_scheduled enrollment (the default). Not accepted for a merchant_initiated enrollment.
Example:
"2026-08-01"
rbs_scheduled (default) — the customer is debited automatically on frequency/startDate/amount. merchant_initiated — the card is stored for on-demand charges via POST /subscriptions/{id}/charge; frequency and startDate are not accepted, and amount is not a recurring amount.
Available options:
rbs_scheduled, merchant_initiated Example:
"rbs_scheduled"
The url used to redirect the user when the enrollment is successful. You must provide a fully-qualified address using https as the scheme.
Maximum string length:
2084The url used to redirect the user when the enrollment fails. You must provide a fully-qualified address using https as the scheme.
Maximum string length:
2084Response
Id of the underlying enrollment payment.
Available options:
successful, failed, pending, action_required Present when status is "action_required". Same shape as a regular payment's nextAction (see PaymentDto) — build and auto-submit a form from action.data.{url, method, data} to complete card enrollment on the hosted card page.
Show child attributes
Show child attributes