Notes

Transaction Object

Parameter

Type

Description

transactionNo

string

The Transaction ID in the Yuansfer system.

reference

string

The Invoice Number of the transaction in the merchant’s system.

originalTransactionNo

string

The ID of the original transaction in the Yuansfer system.

merchantNo

string

Merchant ID

storeNo

string

Store ID

storeAdminNo

string

Store Admin ID

amount

number

The transaction amount in USD.

refundAmount

number

The refund amount.

voidAmount

number

The void or cancel amount.

transactionType

string

The transaction type.

The possible values are: "payment","refund","void".

transactionStatus

string

The status of the transaction

currency

string

The three-character currency code that identifies the currency. The possible values are: "USD" "CNY".

createTime

string

The date and time when the transaction was created.

Format : "yyyy-MM-dd HH:mm:ss".

paymentTime

string

The date and time when the payment was processed.

Format : "yyyy-MM-dd HH:mm:ss".

exchangeRate

number

The exchange rate between USD and CNY.

vendor

string

The payment method.

The possible values are: "alipay", "wechatpay".

Response return code

The Yuansfer APIs return the following codes in the ret_code parameter :

Return Code

Meaning

000000

System Error

000010

API Version Error

000020

Parameter Null Error

000021

Parameter No Related Information

000022

Parameters Do Not Match

000023

Parameter Value Error

000030

No Rights / Access Denied

000040

Transaction Status Error

000080

Supplier System's Error

000100

Success

Transaction status

Status

Meaning

init

A new transaction is created, but not sent to the payment channel.

dealing

Dealing with the payment.

success

The transaction has been successfully processed.

failed

The transaction has failed.

pending

Waiting for the payment confirmation.

closed

The payment channel was setup, but the customer didn’t continue to complete payment action and automatically closed after a certain period.

Instant Payment Notification

The merchants create an IPN listener page on their website and then specify the URL of the listener page in the request body. Yuansfer API then sends notifications of all transaction-related events to that URL. When customers pay for goods or services, the API sends a secure FORM POST containing payment information (IPN messages), to the URL. The IPN listener detects and processes IPN messages using the merchant processes. The IPN listener page contains a custom script or program that waits for back-end messages, validates success status, and then passes them to various back-end applications for processing. The IPN listener has to response 'success' string (not quote) to Yuansfer, otherwise, Yuansfer will send the async payment notification 8 times. IPN is not synchronized with actions on your website. Internet connectivity is not always 100% reliable and IPN messages can be lost or delayed. The IPN service automatically resends messages until the listener acknowledges them. The service resends messages up to 8 times in 2 hours.

Callback Parameters

When the merchant’s system receives a callback from the Yuansfer system, it is recommended that the merchant’s system validates the parameters in the callback information by using the verifySign, to ensure that the data has not been tampered with.

Yuansfer returns the following parameters in callbacks (including IPN).

Parameter

Type

Description

yuansferId

string

The ID of transaction in the Yuansfer system.

status

string

The status of the transaction

amount

string

The transaction amount in USD.

rmbAmount

string

The transaction amount of CNY.

This parameter will be returned only when the payment order contains a 'rmbAmount'.

time

string

The date and time when the transaction was created

Format : "YYYYMMDDHHMMSS".

reference

string

The Invoice Number of the transaction in the merchant’s system.

note

string

The payment note.

scheduleNo

string

The id of recurring transactions,it returns only when vendor=creditcard and creditType=recurring.

currentCount

string

The current count of the number of times an automatic deduction has occurred. Only present when vendor = creditcard and credittype = recurring

verifySign

string

The parameter signature.

Yuansfer Timezone

Yuansfer's working timezone is UTC +8.