3.13. /api/v2/return

Introduction

Return transactions may only be initiated when the transaction have final successful status. See Statuses. For Preauth it makes Cancel transaction, for Capture and SaleReversal. Return transactions are initiated through HTTPS POST request by using URLs and the parameters specified below. Use SHA-1 for authentication.

API URLs

Integration

Production

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

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

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

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

Request Parameters

Note

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

Warning

The following characters must be escaped in the parameter values: & + .

Parameter Name

Description

Value

login

Connecting Party login name.

Necessity: Mandatory
Type: String
Length: 20

orderid

Unique order identifier assigned by Billblend system.

Necessity: Mandatory
Type: String
Length: 20

client_orderid

Unique Connecting Party identifier.

Necessity: Mandatory
Type: String
Length: 128

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. Request parameter: amount (in minor units, if sent).
5. Request parameter: currency (if sent).
6. merchant_control (Control key assigned to Connecting Party account in the Billblend gateway system).
Necessity: Conditional
Type: String
Length: 128

amount

The amount has to be specified in the highest units with . delimiter. For instance, 10.5 for USD means 10 US Dollars and 50 Cents. If this parameter is omitted, initial transaction is reversed as a whole. Amount only makes sense for reversals, not cancels. Amount cannot exceed initial transaction amount. Please note that Currency MUST be specified if amount is specified!

Necessity: Mandatory
Type: Numeric
Length: 10

currency

Currency in which amount is specified. Provided in three-letter currency code format. Example: USD for US Dollar. Reference: Currency Codes.

Necessity: Mandatory
Type: String
Length: 50

comment

A brief description of reason.

Necessity: Mandatory
Type: String
Length: 50

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.

Parameter Name

Description

type

The type of response. May be async-response, validation-error, error. If type equals validation-error or error, error-message and error-code parameters contain error details.

paynet-order-id

Order id assigned to the order by Billblend.

merchant-order-id

Connecting Party order id.

serial-number

Unique number assigned by Billblend server to particular request from the Connecting Party.

end-point-id

Entry point used for processing this transaction.

error-message

If status is error this parameter contains the reason for decline or error details.

error-code

The error code is case of error status.

Request Example

POST /checkout/api/v2/return/39914 HTTP/1.1
Host: sandbox.billblend.com
User-Agent: curl/7.83.0
Accept: */*
Content-Length: 162
Content-Type: application/x-www-form-urlencoded
Connection: close

login=TestMerchant
&client_orderid=Test
&orderid=6862958
&amount=5.00
&currency=RUB
&comment=Service not provided
&control=2dfdb99c4eff5b31c978ecb8bc4b4d094e24c1d4

Success Response Example

HTTP/1.1 200 OK
Server: server
Date: Mon, 08 Aug 2022 07:50:08 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: 141

type=async-response
&serial-number=00000000-0000-0000-0000-000002ddad4a
&merchant-order-id=Test
&paynet-order-id=6862958
&end-point-id=39914

Fail Response Example

HTTP/1.1 200 OK
Server: server
Date: Mon, 08 Aug 2022 10:45:32 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: 153

type=validation-error
&serial-number=00000000-0000-0000-0000-000002ddad5c
&error-message=Reversal+currency+does+not+match+project+currency
&error-code=16

Postman Collection

Request Builder

endpointid or groupid

input ENDPOINTID or ENDPOINTGROUPID

login
client_orderid

input Invoice Number

orderid
amount
currency
merchant_control

input Control Key

comment

String to sign
Signature