3.16. /api/v2/status

Introduction

To make an order status request one have to send an HTTPS POST request to the URLs and the parameters specified below. Use SHA-1 for authentication. See Statuses.

API URLs

Integration

Production

https://sandbox.billblend.com/checkout/api/v2/status/ENDPOINTID

https://pay.billblend.com/checkout/api/v2/status/ENDPOINTID

https://sandbox.billblend.com/checkout/api/v2/status/group/ENDPOINTGROUPID

https://pay.billblend.com/checkout/api/v2/status/group/ENDPOINTGROUPID

Request Parameters

Note

Request must have content-type=application/x-www-form-urlencoded.

Parameter Name

Description

Necessity

login

Merchant login name.

Mandatory

client_orderid

Unique order identifier assigned by merchant.

Mandatory

orderid

Order id assigned to the order by Billblend.

Conditional

by-request-sn

Serial number assigned to the specific request by Billblend. If this field exist in status request, status response return for this specific request. Include this parameter to get the status request with the particular transaction stage (can be used in specific cases). To get the latest transaction status, don’t include this parameter in status request.

Optional

control

Checksum generated by SHA-1. Control string is represented as concatenation of the following parameters:
1. Request parameter: login.
2. Request parameter: client_orderid.
3. Request parameter: orderid.
4. merchant_control (Control key assigned to Connecting Party account in the Billblend gateway system).

Mandatory


In most common cases, the best option is to include both client_orderid and orderid parameters to status request. Order status can be requested with only client_orderid if it’s unique to merchant and orderid is not received. If orderid is not received in response, but this response contains an error, see the received error message to get the information why transaction was not created in the system.

Response Parameters

The same API command for status request is used in multiple Use-Cases, therefore some of the mentioned response parameters might not be present for specific case. Below is the full list of possible 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.
* - these parameters are not defined by default. Please contact tech support to include these fields in callback.

Status Response Parameter

Description

type

The type of response. May be status-response.

status

See Status List for details.

amount

Actual transaction amount. This value can be changed during the transaction flow.

currency

Currency the transaction is charged in (three-letter currency code). Example of valid parameter values are: USD for US Dollar EUR for European Euro.

paynet-order-id

Order id assigned to the order by pay.billblend.com.

merchant-order-id

Connecting Party order id.

phone

Payer’s full international phone number, including country code.

html

HTML code of 3DS authorization form, encoded in application/x-www-form-urlencoded MIME format. Merchant must decode this parameter before showing the form to the Payer. pay.billblend.com System returns the following response parameters when it gets 3DS authorization form from the Issuer Bank. It contains auth form HTML code which must be passed through without any changes to the client’s browser. This parameter exists and has value only when the redirection HTML is already available. For non-3DS this never happens. For 3DS HTML has value after some short time after the processing has been started.

redirect-to

For 3DS authorization the merchant can redirect the Payer to URL provided in this parameter instead of rendering the page provided in html parameter. The redirect-to parameter is returned only if the html parameter is returned. Merchant should use GET HTTP method to redirect. This parameter must be used to work with 3DS 2.0.

serial-number

Unique number assigned by pay.billblend.com server to particular request from the Connecting Party.

last-four-digits

Last four digits of Payer bank card number.

dest-last-four-digits

Last four digits of customer credit card number. Relevant only for transfer transactions.

bin

Bank BIN of Payer bank card number.

card-type

Type of Payer bank card (VISA, MASTERCARD, etc).

gate-partial-reversal

Processing gate support partial reversal (enabled or disabled).

gate-partial-capture

Processing gate support partial capture (enabled or disabled).

transaction-type

Transaction type (sale, reversal, capture, preauth).

processor-rrn

Bank Receiver Registration Number.

processor-tx-id

Acquirer transaction identifier.

receipt-id

Electronic link to receipt https://pay.billblend.com/checkout/view-receipt/ENDPOINTID/receipt-id/.

name

Payer’s name.

card-ref-id

Card reference ID used in subsequent recurrent payments. Relevant only if card-ref-id was created for initial transaction.

cardholder-name

Cardholder’s name.

card-exp-month

Bank card expiration month.

card-exp-year

Bank card expiration year.

card-hash-id

Unique card identifier to use for loyalty programs or fraud checks.

card-country-alpha-three-code

Three letter country code of source card issuer. See Country and State Codes for details.

destination-card-country-alpha-three-code

Three letter country code of destination card issuer. See Country and State Codes for details.

dest-bin

Bank BIN of customer credit card number.

dest-card-type

Type of customer credit card (VISA, MASTERCARD, etc).

dest-bank-name

Bank name by customer card BIN.

destination-hash-id

Unique card identifier to use for loyalty programs or fraud checks. Relevant only for transfer transactions.

destination-card-hash-id

Unique card identifier to use for loyalty programs or fraud checks.

first-name

Payer’s first name.

last-name

Payer’s last name.

email

Payer’s e-mail.

country *

Payer’s country (two-letter country code). Please see Country and State Codes for a list of valid country codes.

state *

Payer’s state . Please see Country and State Codes for a list of valid state codes. Mandatory for USA, Canada and Australia.

city *

Payer’s city.

zip_code *

Payer’s ZIP code.

address1 *

Payer’s address line 1.

purpose

Destination to where the payment goes. It is useful for the merchants who let their payers to top up their accounts with bank card (Mobile phone accounts, game accounts etc.). Sample values are: +7123456789; gamer0001@ereality.com etc. This value can be used by the fraud monitoring system.

bank-name

Bank name by Payer card BIN.

terminal-id

Acquirer terminal identifier to show in receipt.

paynet-processing-date

Acquirer transaction processing date.

approval-code

Bank approval code.

order-stage

The current stage of the transaction processing. See Order Stage for details.

total-reversal-amount

Total amount of processed reversals. Relevant only for reversal transactions.

reversal-amount

The amount of the last processed reversal. Relevant only for reversal transactions.

auth-response-code

Response code used in Iso8583 protocol. Only returned in specific cases.

acquirer-processing-date

Acquirer transaction processing date.

processor-auth-credit-code

Approval credit code. Only returned in specific cases.

processor-credit-rrn

Retrieval Reference Number for credit transaction.

processor-credit-arn

Acquirer card reference number for credit transaction.

processor-debit-arn

Acquirer card reference number for debit transaction.

loyalty-balance

The current bonuses balance of the loyalty program for current operation. if available.

loyalty-message

The message from the loyalty program. if available.

loyalty-bonus

The bonus value of the loyalty program for current operation if available.

loyalty-program

The name of the loyalty program for current operation if available.

descriptor

Bank identifier of the payment recipient.

original-gate-descriptor

Descriptor, which is set on gate level in the system.

error-message

If status in declined, error, filtered this parameter contains the reason for decline.

error-code

The error code is case status in declined, error, filtered.

by-request-sn

Serial number assigned to the specific request by pay.billblend.com. If this field exist in status request, status response return for this specific request.

verified-3d-status

See 3D Secure Status List for details.

verified-rsc-status

Returned if Random Sum Check was performed. See Alternative cardholder authentication

eci

Electronic Commerce Indicator (Visa).

ips-src-payment-product-code

Code for card set by multinational financial service (Visa/Mastercard).

ips-src-payment-product-name

Decrypted code for card set by multinational financial service (Visa/Mastercard).

ips-src-payment-type-code

Type of card code set by multinational financial service (Visa/Mastercard).

ips-src-payment-type-name

Decrypted code for type of card set by multinational financial service (Visa/Mastercard).

merchantdata

If provided in initial request, merchant_data parameter and its value will be included in status response.

initial-amount

Amount, set in initiating transaction, without any fees or commissions. This value can’t change during the transaction flow.

seller-commission

Total commission for processed transaction. This is optional parameter. Please contact your manager in Billblend, if you would like to receive it.

acquirer-commission

Acquirer commission for processed transaction. This is optional parameter. Please contact your manager in Billblend, if you would like to receive it.

motivational-message

This is an optional message which contains extended information about the reason for the declined transaction.

transaction-date

Date of final status assignment for transaction.

orig-amount

Contains the original request amount if it was converted on auxiliary endpoint in Parallel form integration. Relevant only for Payment Cashier transactions.

orig-currency

Contains the original request currency if it was converted on auxiliary endpoint in Parallel form integration. Relevant only for Payment Cashier transactions.

QR Code Status Response Parameters:

Status Response Parameter

Description

qr-code

QR code in base 64 format.

qr-code-payload-type

QR Code type = SBP.

qr-code-payload-value

Link to the QR code =https://qr.nspk.ru/BS***** (only for H2H integration).

PaReqForm Status Response Parameters

Name

Description

tds-pareq-form-pareq

ACS 3DS PaReq data, which received by the Connecting Party.

tds-pareq-form-acs-url

ACS URL to redirect the Payer to 3DS 1.0.2 Authentication Flow.

CReqForm Status Response Parameters

Name

Description

tds-creq-form-creq

A CReq message initiates Cardholder interaction in a Challenge Flow and is used to carry authentication data from the Cardholder. It is formed by the 3DS Server and is posted through the Cardholder’s browser by the merchant to the ACS URL.

tds-creq-form-acs-url

ACS URL to redirect the Payer for Challenge Flow.

MethodUrlFrame Status Response Parameters

Name

Description

tds-method-url-frame-3ds-server-trans-id

Universally unique transaction identifier assigned by the 3DS Server to identify a single transaction.

tds-method-url-frame-3ds-method-url

3DS Method URL used in iframe form which is provided to Payer browser by the merchant.

Rules to form the HTML form.

threeDSMethodData (threeDSMethodNotificationURL + threeDSServerTransID).

Request Example

POST /checkout/api/v2/status/37211 HTTP/1.1
Host: sandbox.billblend.com
User-Agent: curl/7.77.0
Accept: */*
Content-Length: 99
Content-Type: application/x-www-form-urlencoded
Connection: close

login=TestYujik
&client_orderid=123
&orderid=6863082
&control=647f0581bbceb804a73e98d9ea7e78640a75bf1c

Success Response Example

HTTP/1.1 200 OK
Server: server
Date: Mon, 12 Sep 2022 09:02:42 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
X-Cached: EXPIRED
Content-Length: 1275

type=status-response
&serial-number=00000000-0000-0000-0000-000002ddb056
&merchant-order-id=123
&processor-tx-id=PNTEST-6863082
&paynet-order-id=6863082
&status=approved
&amount=555.00
&currency=USD
&descriptor=XXXX
&original-gate-descriptor=XXXX
&gate-partial-reversal=enabled
&gate-partial-capture=enabled
&transaction-type=sale
&receipt-id=081c0c0b-0dd1-3083-b251-e624ac8e57b4
&name=CARD+HOLDER
&cardholder-name=CARD+HOLDER
&card-exp-month=12
&card-exp-year=2099
&email=john.smith%40gmail.com
&last-name=Smith
&first-name=John
&processor-rrn=0225083062885
&approval-code=979249
&order-stage=sale_approved
&merchantdata=VIP+customer
&last-four-digits=2063
&bin=410002
&card-type=VISA
&phone=12063582043
&bank-name=BANCO+ITAUCARD+S.A.
&auth-response-code=00
&terminal-id=12345678
&paynet-processing-date=2022-09-07+13%3A22%3A39+MSK
&acquirer-processing-date=2022-09-07+13%3A22%3A39+MSK
&processor-auth-credit-code=206551
&card-hash-id=2639503
&card-country-alpha-three-code=BRA
&verified-3d-status=NOT_AUTHENTICATED
&processor-credit-rrn=0225060914211
&processor-credit-arn=809124106
&processor-debit-arn=601904020
&purpose=user_account1
&ips-src-payment-product-code=F
&ips-src-payment-product-name=Visa+Classic
&ips-src-payment-type-code=Credit
&ips-src-payment-type-name=VISA+Credit
&initial-amount=555.00

Fail Response Example

HTTP/1.1 200 OK
Server: server
Date: Mon, 12 Sep 2022 09:08:02 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
X-Cached: MISS
Content-Length: 137

type=validation-error
&serial-number=00000000-0000-0000-0000-000002ddb057
&error-message=End+point+with+id+372118+not+found
&error-code=3

Postman Collection

Request Builder

endpointid or groupid

input ENDPOINTID or ENDPOINTGROUPID

login

input Login

client_orderid

input Invoice Number

orderid
merchant_control

input Control Key

by-request-sn

String to sign
Signature