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

IntegrationProduction
https://sandbox.billblend.com/checkout/api/v4/create-card-ref/ENDPOINTIDhttps://pay.billblend.com/checkout/api/v4/create-card-ref/ENDPOINTID
https://sandbox.billblend.com/checkout/api/v4/create-card-ref/group/ENDPOINTGROUPIDhttps://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 ParametersDescription
loginConnecting Party’s login name.
client_orderidConnecting Party’s order identifier of the transaction.
orderidTransaction 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 ParameterDescription
typeThe type of response. May be create-card-ref-responsevalidation-errorerror. If type equals validation-error or errorerror-message and error-code parameters contain error details.
serial-numberUnique number assigned by Billblend server to particular request from the Connecting Party.
card-ref-idCard reference ID used in subsequent recurring payments.
unq-card-ref-idUnique card reference ID to each PAN. It can be used by Connecting Party for loyalty programs or fraud control.
recurring-payment-idPayer’s tokenized cardholder’s data ID, referred as Recurring Payment ID (RPI).
dst-card-ref-idReceiver’s card reference ID used in subsequent recurring payments. Can be used only in transfer APIs.
dst-unq-card-ref-idReceiver’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-idReceiver’s tokenized cardholder’s data ID, referred as Recurring Payment ID (RPI). Can be used only in transfer APIs.
error-messageIf status is declined or error this parameter contains the reason for decline.
error-codeThe error code is case of declined or error status.
statusSee 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
loginyour 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_fields
import 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();
            }
        }
    }
}

Contact us

By clicking on the button, you agree to the data protection policy

Complete the quiz

By clicking on the button, you agree to the data protection policy