3.19. /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.connpay.com/paynet/api/v4/create-card-ref/ENDPOINTID	https://gate.connpay.com/paynet/api/v4/create-card-ref/ENDPOINTID
https://sandbox.connpay.com/paynet/api/v4/create-card-ref/group/ENDPOINTGROUPID	https://gate.connpay.com/paynet/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 ConnPay 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 /paynet/api/v4/create-card-ref/39915 HTTP/1.1
Host: sandbox.connpay.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

Request Builder

Insert PKCS#1 PEM private key for sandbox environment in the field below. Request builder supports up to 4096 key length.

Debug form

URL
login	your login will be used as Consumer Public for OAuth header, not included as request body parameter
client_orderid
orderid

Normalized parameters string to sign, according to OAuth 1.0a rules

POST body parameters to submit

OAuth 1.0a headers to submit.

HEX Encoded Signature

^{* HEX encoded string is for debug purposes only. You shouldn't send this string to the server neither in HEX nor in Encoded HEX representation.}

Base64 Encoded Signature

^{* Binary RSA-SHA256 signature directly encoded in base64 should be sent to the server.}