Return to Vault

Protocol

LUUP Payment API is based on JSON RPC 2.0 protocol. All the endpoints include version prefix: /v1.

Endpoint

Authentication

We use HTTP Basic Authentication to control access to LUUP API.
Authorize to see API credentials

Errors

See errors in JSON RPC 2.0

Error code summary

-32700 Invalid JSON was received by the server.
-32600 The JSON sent is not a valid Request object.
-32601 The method does not exist / is not available.
-32602 Invalid method parameter(s).
-32603 Invalid method parameter(s).
401 Wrong authorization credentials.
404 Requested resource doesn't exist.
503 Service temporary unavailable.
1000 Method execution failed with given arguments values.

Methods

paymentRequest

Returns HTML that redirects to payment page. After payment is processed, the customer will be redirected to the returnUrl with transaction ID specified. notifyUrl will be used to report payment status.

Arguments

Argument Type Description Required
type string Preferred payment type: wechat, alipay, qq, bank
amount float Payment amount in corresponding currency
currency string Currency code (e.g. EUR, USD, CNY)
orderId string Unique order ID
orderDescription string Order description string (e.g. MacBook Pro) -
firstName string Customer first name
middleName string Customer middle name -
lastName string Customer last name
birthday string Customer birthday in YYYY-MM-DD format (required for cards) -
email string Customer email (required for cards)
phone string Customer phone number (in international format +12345678912)
country string Customer country (required for cards)
state string Customer state -
city string Customer city (required for cards)
address string Customer address (required for cards)
postCode string Customer postal code (required for cards) -
returnUrl string When payment will be proceeded, user will be redirected to this URL by POST request containing payment status data (see TransactionStatus model
notifyUrl string Payment result data will be sent to this URL in application/x-www-form-urlencoded POST request (see TransactionStatus model) when payment status is updated. Merchant service must response with TransactionStatus.transactionId string i.e. "48PirbvW4Q", otherwise status update request will be sent again, every 5 minutes, until correct response will be received. -

Return

Type Description
PaymentRequestResult Payment processing HTML code with transaction ID

bankPaymentRequest

Returns HTML that redirects to specific bank payment page. After payment is processed, the customer will be redirected to the returnUrl with transaction ID specified. notifyUrl will be used to report payment status.

Arguments

Argument Type Description Required
amount float Payment amount
currency string Currency code (e.g. EUR, USD, CNY)
bankCode string Bank code (see getBanks() method)
orderId string Unique order ID
orderDescription string Order description string (e.g. MacBook Pro) -
firstName string Customer first name
middleName string Customer middle name -
lastName string Customer last name
birthday string Customer birthday in YYYY-MM-DD format (required for cards) -
email string Customer email (required for cards)
phone string Customer phone number (in international format +12345678912)
country string Customer country (required for cards)
state string Customer state -
city string Customer city (required for cards)
address string Customer address (required for cards)
postCode string Customer postal code (required for cards) -
returnUrl string When payment will be proceeded, user will be redirected to this URL by POST request containing payment status data (see TransactionStatus model
notifyUrl string Payment status update will be sent to this URL in application/x-www-form-urlencoded POST request (see TransactionStatus model) when payment status is updated. Merchant service must response with TransactionStatus.transactionId string i.e. "48PirbvW4Q", otherwise status update request will be sent again, every 5 minutes, until correct response will be received. -

Return

Type Description
PaymentRequestResult Payment processing HTML code with transaction ID

getBanks

Get banks names and codes supported by bankPaymentRequest() method

Return

Type Description
array Array of bank codes and names

payoutToBank

Create payout transfer request to bank account

Arguments

Argument Type Description Required
amount float Payout amount
currency string Currency code (e.g. CNY)
bankCode string Bank code (see getPayoutBanks() method)
bankBranch string Bank branch name
bankCityCode string Code of city where bank is located (see getPayoutCities() method)
accountNumber string Bank account number
firstName string Beneficiary first name
lastName string Beneficiary last name
email string Beneficiary email (required for cards)
phone string Beneficiary phone number (in international format +12345678912)
orderId string Unique order ID -
notifyUrl string Payout status will be sent to this URL in application/x-www-form-urlencoded POST request (see TransactionStatus model) when payout status is updated. Merchant service must response with TransactionStatus.transactionId string i.e. "48PirbvW4Q", otherwise status update request will be sent again, every 5 minutes, until correct response will be received. -

Return

Type Description
string Transaction ID

getPayoutBanks

Get banks names and codes supported by payoutToBank() method

Return

Type Description
array Array of banks codes and names

getPayoutCities

Get Chinese cities names and codes supported by payoutToBank() method

Return

Type Description
array Array of cities codes and names

getTransactions

Get collection of transactions

Arguments

Argument Type Description Required
offset number Start selection from specified row -
limit number Limit selection for specified row numbers [default: 100] -
filter Filter Filter selection by set of criteries -

Return

Type Description
TransactionsCollection Limited collection of transactions with total amount

getTransaction

Get transaction by ID

Arguments

Argument Type Description Required
id string Unique transaction ID

Return

Type Description
Transaction Transaction object

getTransactionStatus

Get transaction status

Arguments

Argument Type Description Required
id string Unique transaction ID

Return

Type Description
string Transaction status (pending, success, failed)

alipay.requestPaymentQrCode

Request QR code for AliPay payment.

Arguments

Argument Type Description Required
amount float Payment amount in corresponding currency
currency string Currency code (e.g. EUR, USD, CNY)
orderId string Unique order ID
orderDescription string Order description string (e.g. MacBook Pro)
firstName string Customer first name
lastName string Customer last name
country string Customer country
state string Customer state -
city string Customer city
address string Customer address
postCode string Customer postal code
email string Customer email
phone string Customer phone number (in international format +12345678912)
notifyUrl string Payment result data will be sent to this URL in application/x-www-form-urlencoded POST request (see TransactionStatus model) when payment status is updated. Merchant service must response with TransactionStatus.transactionId string i.e. "48PirbvW4Q", otherwise status update request will be sent again, every 5 minutes, until correct response will be received.

Return

Type Description
QrCode QR code with transaction ID

wechat.requestPaymentQrCode

Request QR code for WeChat payment.

Arguments

Argument Type Description Required
amount float Payment amount in corresponding currency
currency string Currency code (e.g. EUR, USD, CNY)
orderId string Unique order ID
orderDescription string Order description string (e.g. MacBook Pro)
firstName string Customer first name
lastName string Customer last name
country string Customer country
state string Customer state -
city string Customer city
address string Customer address
postCode string Customer postal code
email string Customer email
phone string Customer phone number (in international format +12345678912)
notifyUrl string Payment result data will be sent to this URL in application/x-www-form-urlencoded POST request (see TransactionStatus model) when payment status is updated. Merchant service must response with TransactionStatus.transactionId string i.e. "48PirbvW4Q", otherwise status update request will be sent again, every 5 minutes, until correct response will be received.

Return

Type Description
QrCode QR code with transaction ID

qq.requestPaymentQrCode

Request QR code for QQ payment.

Arguments

Argument Type Description Required
amount float Payment amount in corresponding currency
currency string Currency code (e.g. EUR, USD, CNY)
orderId string Unique order ID
orderDescription string Order description string (e.g. MacBook Pro)
firstName string Customer first name
lastName string Customer last name
country string Customer country
state string Customer state -
city string Customer city
address string Customer address
postCode string Customer postal code
email string Customer email
phone string Customer phone number (in international format +12345678912)
notifyUrl string Payment result data will be sent to this URL in application/x-www-form-urlencoded POST request (see TransactionStatus model) when payment status is updated. Merchant service must response with TransactionStatus.transactionId string i.e. "48PirbvW4Q", otherwise status update request will be sent again, every 5 minutes, until correct response will be received.

Return

Type Description
QrCode QR code with transaction ID

Models

In this section you can find out about models and example data structures for them.

PaymentRequestResult

Name Type Description Required
transactionId string Transaction ID
html string Payment processing HTML code that will redirect customer to payment page

TransactionStatus

Name Type Description Required
transactionId string Unique transaction ID
orderId string Unique order ID
amount float Payment amount in corresponding currency
currency string Currency code (e.g. EUR, USD, CNY)
status string Transaction processing status (pending, success, failed)
signature string Result data verification signature: MD5(apiId + ';' + apiKey + ';' + transactionId + ';' + orderId + ';' + amount + ';' + currency + ';' + status)

Transaction

Name Type Description Required
id string Unique transaction ID
currency string Currency code (e.g. EUR, USD, CNY)
amount float Order amount in corresponding currency
paymentType string Payment method used for this transaction (DB - payment, PAYOUT, REFUND)
status string Transaction processing status (pending, success, failed)
datetime string Datetime when transaction was created in UTC timezone
orderId string Unique order ID
orderDescription string Order description string (e.g. MacBook Pro) -
returnUrl string URL used to redirect customer after payment was processed
notifyUrl string URL used to notify merchant service about payment status update
firstName string Customer first name -
middleName string Customer middle name -
lastName string Customer last name -
email string Customer email -

Filter

Name Type Description Required
ids array Array of transactions IDs -
amount float Payment amount -
currency string Currency code (e.g. EUR, USD, CNY) -
status string Transaction processing status (pending, success, failed) -
paymentType string Payment method used for this transaction (DB - payment, PAYOUT, REFUND) -
orderId string Unique order ID -
orderDescription string Order description string (e.g. MacBook Pro) -
datetimeFrom string Earliest transactions datetime -
datetimeTo string Oldest transactions datetime -

TransactionsCollection

Name Type Description Required
total number Total amount of transactions in selection (ignoring limit)
transactions Transaction [ ] Array of transactions

QrCode

Name Type Description Required
transactionId string Transaction ID in LUUP
qrCode string QR code URL
qrCodeImageUrl string Rendered QR code image URL (to set size and padding add ?s=150&p=10 query parameters)