3.18. /api/v4/create-card-ref
Introduction
Card reference ID and Recurring Payment ID creation is initiated through HTTPS POST request by using URLs and the parameters specified below. Use OAuth RSA-SHA256 for authentication.
API URLs
| Integration | Production |
|---|---|
| https://sandbox.billblend.com/checkout/api/v4/create-card-ref/ENDPOINTID | https://pay.billblend.com/checkout/api/v4/create-card-ref/ENDPOINTID |
| https://sandbox.billblend.com/checkout/api/v4/create-card-ref/group/ENDPOINTGROUPID | https://pay.billblend.com/checkout/api/v4/create-card-ref/group/ENDPOINTGROUPID |
Request Parameters
Note
Request must have content-type=application/x-www-form-urlencoded and Authorization headers.
| Sale Request Parameters | Description |
|---|---|
| login | Connecting Party’s login name. |
| client_orderid | Connecting Party’s order identifier of the transaction. |
| orderid | Transaction order identifier assigned by Payment Gateway. |
Connecting Party has to supply orderid and client_orderid associated with the first payment transaction. It emphasizes that the first payment is a mandatory step to process recurring payments. To authorize the credit card the information about it must be sufficient and an initial payment must be in final status.
Response Parameters
Note
Response has Content-Type: text/html;charset=utf-8 header. All fields are x-www-form-urlencoded, with (0xA) character at the end of each parameter’s value.
| Registration Response Parameter | Description |
|---|---|
| type | The type of response. May be create-card-ref-response, validation-error, error. If type equals validation-error or error, error-message and error-code parameters contain error details. |
| serial-number | Unique number assigned by Billblend server to particular request from the Connecting Party. |
| card-ref-id | Card reference ID used in subsequent recurring payments. |
| unq-card-ref-id | Unique card reference ID to each PAN. It can be used by Connecting Party for loyalty programs or fraud control. |
| recurring-payment-id | Payer’s tokenized cardholder’s data ID, referred as Recurring Payment ID (RPI). |
| dst-card-ref-id | Receiver’s card reference ID used in subsequent recurring payments. Can be used only in transfer APIs. |
| dst-unq-card-ref-id | Receiver’s unique card reference ID to each PAN. It can be used by Connecting Party for loyalty programs or fraud control. Can be used only in transfer APIs. |
| dst-recurring-payment-id | Receiver’s tokenized cardholder’s data ID, referred as Recurring Payment ID (RPI). Can be used only in transfer APIs. |
| error-message | If status is declined or error this parameter contains the reason for decline. |
| error-code | The error code is case of declined or error status. |
| status | See Status List for details. |
Request Example
POST /checkout/api/v4/create-card-ref/39915 HTTP/1.1 Host: sandbox.billblend.com User-Agent: curl/7.83.0 Accept: */* Authorization: OAuth oauth_consumer_key="TestMerchant", oauth_nonce="KT6cZmuVGqg0V6Jm2RE3q4o79KXC1v2q", oauth_signature="KucF0eYk3WZCV7oKwOi1z6PR%2BkHxiZwPucD6Sx%2BX2mV%2BbaidPy9K9USh8ciMKM60NNl1LYYjywdaErB1uTIdFFbQ8ZKs8M1smaMPOaHDaApceTOlDh6E7u3BzBTKYhBc%2BWnksZz9Wyz8%2B39lHCIODo0KZmNmXCTjjZmlx%2FrFNkK%2FhwJV9Kwq1nPbA5QZTkF686O0O0lHFy3Prx649AIRgsrqDLb5%2FgHL9M8fSScVUPnGdLGJ2hSgKJFpIOFibT0nC89Xg8odn1hR9WIa1650glaqZntSkocBzXAkOKa7kIbSOZW1sFCiBjksy6o1sny9hmc%2F9cC9t86RoEY1QhVYuvOLztQm1dLhpRy%2FPOL9LCmIzO3B%2FUB2wJUXPkEyFsSLZVeqQl%2B0IukljV6Cr1ZfuyUktbvvXJsnod5AK%2FsV2GaxEf%2BttqqWv%2FFNjPLoUZYrPB6rKsIpw%2FOftinIwIxYzLY3FMmbKQd6zxnMJLJm7M2s6cQFGiAnfgvZFAMZhugBuuigy4T9Ckq1t5N9vQkl2htDv0TTnswx50wpF%2F7OKiXTVFNqOE%2FCj%2F07ZwZbxbD%2FMxKhOhfNMME1jGxzgI0wEj1166eKpxnCOk%2BTlYTJvNW5%2BbKuGnU43Q2Nmga0aQ007NKRfIV%2FWk6e%2BUuGO48wGdi0CiKxS9hpnpvjyPLc%2BsA%3D", oauth_signature_method="RSA-SHA256", oauth_timestamp="1673335450", oauth_version="1.0" Content-Length: 40 Content-Type: application/x-www-form-urlencoded Connection: close client_orderid=34T43R77N &orderid=6868305
Success Response Example
HTTP/1.1 200 Server: server Date: Tue, 10 Jan 2023 07:24:36 GMT Content-Type: text/html;charset=utf-8 Connection: close Vary: Accept-Encoding X-XSS-Protection: 1 X-Content-Type-Options: nosniff Strict-Transport-Security: max-age=31536000 Content-Language: en-US Strict-Transport-Security: max-age=31536000 Content-Length: 174 type=create-card-ref-response &serial-number=00000000-0000-0000-0000-000002de3113 &card-ref-id=1461608 &recurring-payment-id=1491863 &dst-card-ref-id=1461608 &status=approved
Fail Response Example
HTTP/1.1 403
Server: server
Date: Tue, 10 Jan 2023 07:34:08 GMT
Content-Type: text/html
Content-Length: 735
Connection: close
X-XSS-Protection: 1
X-Content-Type-Options: nosniff
Strict-Transport-Security: max-age=31536000
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
<title>403</title>
<style type="text/css">
body {
font-family: Arial, sans-serif;
font-size: 130%;
background-color: #eee;
}
p {
margin: 10em auto 0;
width: 500px;
border: 1px solid gray;
text-align: center;
vertical-align: middle;
padding: 40px 20px;
background-color: #fff;
-webkit-border-radius: 20px;
-moz-border-radius: 20px;
border-radius: 20px;
}
</style>
</head>
<body>
<p>Access is denied</p>
</body>
</html>
Postman Collection
Postman Collection is available at this link – https://doc.billblend.com/integration/API_commands/api_v4_create-card-ref.html#postman-collection
Request Builder
Request Builder is available at this link – https://doc.billblend.com/integration/API_commands/api_v4_create-card-ref.html#request-builder
Debug form
| URL | ||
|---|---|---|
| login | your login will be used as Consumer Public for OAuth header, not included as request body parameter | |
| client_orderid | ||
| orderid |
curl -H 'Authorization: OAuth oauth_consumer_key="paydroid", oauth_nonce="gE2SqlUrCKZJnlOzzYJbVZCpBjb2LHKy", oauth_signature="n3CU4YatliYzYtaZBsxO7bvtjfpQiarKjwghh5t0aI0PtOjliim%2BFqbqJ3kZl3XFVGbl%2FbZb8L3FePdMaga5mez7mch%2FmJJmuxCgpNtWOtV7%2Fr6dM5%2F4yHeQxBiLfdF4be6j%2FSUXzSK4r5xYcndp1mg%2FhlfFMVFKCRBGB2Re6sZ2Nvbw%2BxZ0MgIa7H%2F8TWczBWXpuCoPbef1YUsbANnST9CxRa6t%2FX%2F5C7jMEG%2ByOXEqySVmaDYnRFD3Qw1lCoYSbCPYclO31LMMr5Y3HFf9bfbrA2sWREgL1ihquKWBvzY5Zaz%2FU6w%2BEqDCYOOxud55oiG9deX3eB3kvWVimSzkHpWBfSyxtrp%2FyObR7d4i%2B0PPr0ZwCZ1%2BOUcvfFeEkK0vzTNt4xMH98yn4ANYaLTKTLlfJH8ytjlvZsBdK72LS80HxwEcxeGfJc5Yeb%2FB6AGTolifyEgMRptCzivFJPfE%2B4x6G0zakGpeYbhfKP9xrKMGfmzQPUGXx%2BCRiLzQ%2FQRzBpA3dq5jpKOzjdYOgUEkpbP%2FM2JAJ4FvNJ8DOZxdEqP2UMImsllKHMmYGIqb7ZI1smU1usvB2xV2XyCeqQcoplYs0l2rqOY1EyLixWlanxF9nFpegYL67WGuqVqvBfe4fA648%2BRHOw7vySshVb9VLumU%2BhAduWWa6QNY%2B5X4NUo%3D", oauth_signature_method="RSA-SHA256", oauth_timestamp="1753198939", oauth_version="1.0"' --data 'client_orderid=1&orderid=1' 'https://sandbox.billblend.com/checkout/api/v4/create-card-ref/ENDPOINTID'<?php
/**
* Executes request
*
* @param string $url Url for payment method
* @param array $requestFields Request data fields
* @param array $customHeaders Custom request headers
*
* @return array Host response fields
*
* @throws RuntimeException Error while executing request
*/
function sendRequest($url, array $requestFields, array $customHeaders = array())
{
$curl = curl_init($url);
curl_setopt_array($curl, array
(
CURLOPT_HEADER => 1,
CURLOPT_USERAGENT => 'Billblend-Client/1.0',
CURLOPT_SSL_VERIFYHOST => 0,
CURLOPT_SSL_VERIFYPEER => 0,
CURLOPT_POST => 1,
CURLOPT_RETURNTRANSFER => 1
));
$headersJoiner = function($key, $value) {
return "{$key}: {$value}";
};
curl_setopt($curl, CURLOPT_HTTPHEADER, array_map($headersJoiner, array_keys($customHeaders), array_values($customHeaders)));
curl_setopt($curl, CURLOPT_POSTFIELDS, http_build_query($requestFields));
$response = curl_exec($curl);
if(curl_errno($curl))
{
$error_message = 'Error occurred: ' . curl_error($curl);
$error_code = curl_errno($curl);
}
elseif(curl_getinfo($curl, CURLINFO_HTTP_CODE) != 200)
{
$error_code = curl_getinfo($curl, CURLINFO_HTTP_CODE);
$error_message = "Error occurred. HTTP code: '{$error_code}'. Response: {$response}";
}
curl_close($curl);
if (!empty($error_message))
{
throw new RuntimeException($error_message, $error_code);
}
if(empty($response))
{
throw new RuntimeException('Host response is empty');
}
$responseFields = array();
parse_str($response, $responseFields);
return $responseFields;
}
$requestFields = array(
'client_orderid' => '1',
'orderid' => '1',
);
$customHeaders = array(
'Authorization' => 'OAuth oauth_consumer_key="paydroid", oauth_nonce="gE2SqlUrCKZJnlOzzYJbVZCpBjb2LHKy", oauth_signature="n3CU4YatliYzYtaZBsxO7bvtjfpQiarKjwghh5t0aI0PtOjliim%2BFqbqJ3kZl3XFVGbl%2FbZb8L3FePdMaga5mez7mch%2FmJJmuxCgpNtWOtV7%2Fr6dM5%2F4yHeQxBiLfdF4be6j%2FSUXzSK4r5xYcndp1mg%2FhlfFMVFKCRBGB2Re6sZ2Nvbw%2BxZ0MgIa7H%2F8TWczBWXpuCoPbef1YUsbANnST9CxRa6t%2FX%2F5C7jMEG%2ByOXEqySVmaDYnRFD3Qw1lCoYSbCPYclO31LMMr5Y3HFf9bfbrA2sWREgL1ihquKWBvzY5Zaz%2FU6w%2BEqDCYOOxud55oiG9deX3eB3kvWVimSzkHpWBfSyxtrp%2FyObR7d4i%2B0PPr0ZwCZ1%2BOUcvfFeEkK0vzTNt4xMH98yn4ANYaLTKTLlfJH8ytjlvZsBdK72LS80HxwEcxeGfJc5Yeb%2FB6AGTolifyEgMRptCzivFJPfE%2B4x6G0zakGpeYbhfKP9xrKMGfmzQPUGXx%2BCRiLzQ%2FQRzBpA3dq5jpKOzjdYOgUEkpbP%2FM2JAJ4FvNJ8DOZxdEqP2UMImsllKHMmYGIqb7ZI1smU1usvB2xV2XyCeqQcoplYs0l2rqOY1EyLixWlanxF9nFpegYL67WGuqVqvBfe4fA648%2BRHOw7vySshVb9VLumU%2BhAduWWa6QNY%2B5X4NUo%3D", oauth_signature_method="RSA-SHA256", oauth_timestamp="1753198939", oauth_version="1.0"'
);
$responseFields = sendRequest('https://sandbox.billblend.com/checkout/api/v4/create-card-ref/ENDPOINTID', $requestFields, $customHeaders);
print_r($responseFields);
?>require 'net/http'
require 'uri'
require 'cgi'
##
# Executes request
#
# @param url [String] Url for payment method
# @param request_fields [Hash] Request data fields
# @param custom_headers [Hash] Custom request headers
#
# @return [Hash] Host response fields
def send_request(url, request_fields, custom_headers = [])
begin
uri = URI url
response = Net::HTTP.start uri.hostname, uri.port, :use_ssl => uri.scheme == 'https' do |http|
post = Net::HTTP::Post.new uri.request_uri
post.set_form_data request_fields
custom_headers.each do |key, value|
post[key] = value
end
http.request post
end
rescue Exception => e
raise RuntimeError, "Error occurred. #{e.message}"
end
unless Net::HTTPOK === response
raise RuntimeError, "Error occurred. HTTP code: '#{response.code}'. Response: '#{response.body}'"
end
unless response.body
raise RuntimeError, 'Host response is empty'
end
# Change hash format from {'key' => ['value']} to {'key' => 'value'} in map block
Hash[CGI.parse(response.body).map {|key, value| [key, value.first]}]
end
request_fields = {
'client_orderid' => '1',
'orderid' => '1',
}
custom_headers = {
'Authorization' => 'OAuth oauth_consumer_key="paydroid", oauth_nonce="gE2SqlUrCKZJnlOzzYJbVZCpBjb2LHKy", oauth_signature="n3CU4YatliYzYtaZBsxO7bvtjfpQiarKjwghh5t0aI0PtOjliim%2BFqbqJ3kZl3XFVGbl%2FbZb8L3FePdMaga5mez7mch%2FmJJmuxCgpNtWOtV7%2Fr6dM5%2F4yHeQxBiLfdF4be6j%2FSUXzSK4r5xYcndp1mg%2FhlfFMVFKCRBGB2Re6sZ2Nvbw%2BxZ0MgIa7H%2F8TWczBWXpuCoPbef1YUsbANnST9CxRa6t%2FX%2F5C7jMEG%2ByOXEqySVmaDYnRFD3Qw1lCoYSbCPYclO31LMMr5Y3HFf9bfbrA2sWREgL1ihquKWBvzY5Zaz%2FU6w%2BEqDCYOOxud55oiG9deX3eB3kvWVimSzkHpWBfSyxtrp%2FyObR7d4i%2B0PPr0ZwCZ1%2BOUcvfFeEkK0vzTNt4xMH98yn4ANYaLTKTLlfJH8ytjlvZsBdK72LS80HxwEcxeGfJc5Yeb%2FB6AGTolifyEgMRptCzivFJPfE%2B4x6G0zakGpeYbhfKP9xrKMGfmzQPUGXx%2BCRiLzQ%2FQRzBpA3dq5jpKOzjdYOgUEkpbP%2FM2JAJ4FvNJ8DOZxdEqP2UMImsllKHMmYGIqb7ZI1smU1usvB2xV2XyCeqQcoplYs0l2rqOY1EyLixWlanxF9nFpegYL67WGuqVqvBfe4fA648%2BRHOw7vySshVb9VLumU%2BhAduWWa6QNY%2B5X4NUo%3D", oauth_signature_method="RSA-SHA256", oauth_timestamp="1753198939", oauth_version="1.0"'
}
response_fields = send_request('https://sandbox.billblend.com/checkout/api/v4/create-card-ref/ENDPOINTID', request_fields, custom_headers);
require 'pp'
pp response_fieldsimport java.io.*;
import java.net.HttpURLConnection;
import java.net.URL;
public class Main {
//Transactions are initiated by using URL in the following format: /checkout/api/v4/TRANSACTION_TYPE/ENDPOINTID or /checkout/api/v4/TRANSACTION_TYPE/ENDPOINTGROUPID (if group is supported)
//Use "gate" for production purposes or "sandbox" for integration needs
private static String targetURL = "https://sandbox.billblend.com/checkout/api/v4/create-card-ref/ENDPOINTID";
//Request parameters
private static String urlParameters = "client_orderid=1&orderid=1";
public static void main(String[] args) {
//Sending POST request to the specified URL with request parameters
System.out.println(executePost(targetURL, urlParameters));
}
public static String executePost(String targetURL, String urlParameters)
{
URL url;
HttpURLConnection connection = null;
try {
//Create connection
url = new URL(targetURL);
connection = (HttpURLConnection)url.openConnection();
connection.setDoOutput(true);
boolean hasHeaders = true;
if(hasHeaders){
String header ="OAuth oauth_consumer_key=\"paydroid\", oauth_nonce=\"gE2SqlUrCKZJnlOzzYJbVZCpBjb2LHKy\", oauth_signature=\"n3CU4YatliYzYtaZBsxO7bvtjfpQiarKjwghh5t0aI0PtOjliim%2BFqbqJ3kZl3XFVGbl%2FbZb8L3FePdMaga5mez7mch%2FmJJmuxCgpNtWOtV7%2Fr6dM5%2F4yHeQxBiLfdF4be6j%2FSUXzSK4r5xYcndp1mg%2FhlfFMVFKCRBGB2Re6sZ2Nvbw%2BxZ0MgIa7H%2F8TWczBWXpuCoPbef1YUsbANnST9CxRa6t%2FX%2F5C7jMEG%2ByOXEqySVmaDYnRFD3Qw1lCoYSbCPYclO31LMMr5Y3HFf9bfbrA2sWREgL1ihquKWBvzY5Zaz%2FU6w%2BEqDCYOOxud55oiG9deX3eB3kvWVimSzkHpWBfSyxtrp%2FyObR7d4i%2B0PPr0ZwCZ1%2BOUcvfFeEkK0vzTNt4xMH98yn4ANYaLTKTLlfJH8ytjlvZsBdK72LS80HxwEcxeGfJc5Yeb%2FB6AGTolifyEgMRptCzivFJPfE%2B4x6G0zakGpeYbhfKP9xrKMGfmzQPUGXx%2BCRiLzQ%2FQRzBpA3dq5jpKOzjdYOgUEkpbP%2FM2JAJ4FvNJ8DOZxdEqP2UMImsllKHMmYGIqb7ZI1smU1usvB2xV2XyCeqQcoplYs0l2rqOY1EyLixWlanxF9nFpegYL67WGuqVqvBfe4fA648%2BRHOw7vySshVb9VLumU%2BhAduWWa6QNY%2B5X4NUo%3D\", oauth_signature_method=\"RSA-SHA256\", oauth_timestamp=\"1753198939\", oauth_version=\"1.0\"";
connection.setRequestProperty("Authorization", header);
connection.setRequestProperty("cache-control", null);
connection.setRequestProperty("pragma", null);
}
//Send request
DataOutputStream wr = new DataOutputStream (
connection.getOutputStream ());
wr.writeBytes (urlParameters);
wr.flush ();
wr.close ();
//Get Response
InputStream is = connection.getInputStream();
BufferedReader rd = new BufferedReader(new InputStreamReader(is));
String line;
StringBuffer response = new StringBuffer();
while((line = rd.readLine()) != null) {
response.append(line);
response.append('\n');
}
rd.close();
return response.toString();
} catch (Exception e) {
e.printStackTrace();
return null;
} finally {
if(connection != null) {
connection.disconnect();
}
}
}
}