Alipay direct payment processing
Endpoints
HTTP Method | API URL | API Version |
---|---|---|
POST | https://connect2.payxpert.com/payment/{customerToken}/process/alipay/direct | >= 002.60 |
This call permits to process directly a Alipay payment without going through the payment page.
It can be used when embedding the process in a Web application or in a native mobile application for example.
A payment creation call must be done prior to this call using the Alipay payment method.
Then the Alipay direct payment processing call is done using in the URL the customerToken parameter returned by this previous call.
Once this is done the final payment status still needs to be confirmed.
According to the chosen Alipay payment mode three behaviors are possible:
- POS mode, in this mode it is the shopper that scans the QRCode displayed by the merchant system, the call returns:
- Information to build the QRCode to display to the shopper
- A WebSocket URL that can be used to wait for the payment processing and receive the status through it once the shopper has scanned the QRCode and confirmed the payment in Alipay application
- The identifier of the transaction that can be used to get the information by polling the server (if WebSocket use is not possible)
- APP mode, in this mode it is the merchant that scans the shopper’s Barcode or QRCode displayed in the Alipay app and transmit it in the direct process request:
- In case the payment is accepted right away, the call returns directly the transaction information containing the result of the payment
- In case the payment needs extra time to be confirmed, the behavior is the same as POS mode, a WebSocket URL is returned to monitor the payment status in real time
- SDK mode, used when the payment must be done embedded in a mobile application, in that mode the call will return everything that is needed by the Alipay SDK to process a payment directly inside the application. This mode requires a server side middleware that will process this call using the authentication and return the result to the mobile application. Only available if account has a special agreement.
Accepted parameters
The body of the request to a direct Alipay process is in JSON format. It can contain the following parameters.
Name | Type | Description | Required | API Version |
---|---|---|---|---|
apiVersion | String(8) | API version to be used (default 002.60) | no | >= 002.60 |
mode | String(10) | The Alipay payment mode to use. Either pos, app or sdk | yes | >= 002.60 |
buyerIdentityCode | String(32) | The code coming from the shopper’s Alipay application | yes if mode is app, ignored otherwise |
>= 002.60 |
identityCodeType | String(16) | The type of code coming from the shopper’s Alipay application, either qrcode or barcode | yes if mode is app, ignored otherwise |
>= 002.60 |
sdkOsType | String | In SDK mode, the operating system type, either android or ios | yes if mode is sdk, ignored otherwise |
>= 002.72 |
sdkRedirectUrl | String(2048) | In SDK mode, the URL to redirect the shopper to after payment has been validated on the mobile device | no | >= 002.72 |
notificationLang | String(2) | Language code to use for shopper’s email notifications, if enabled (default en) | no | >= 002.60 |
notificationTimeZone | String(64) | The time zone to use for shopper’s email notifications, if enabled (default Etc/Utc) | no | >= 002.60 |
Response
The body of the response to a direct Alipay process is in JSON format.
The following fields are present in the response :
Name | Type | Description | API Version |
---|---|---|---|
code | String(3) | API response code (see response codes for possible values) | >= 002 |
message | String(128) | Human readable message associated with the code | >= 002 |
apiVersion | String(8) | API version. | >= 002.60 |
exchangeRate | Double | The exchange rate between the currency of the payment and the RMB currency. For information only. | >= 002.60 |
qrCode | String(2048) | The QR code to be displayed to the shopper in the case of native mode. It is a base 64 encoded PNG image. | >= 002.60 |
qrCodeUrl | String(128) | The URL embedded in the QR code in case of POS mode, to be used to produce a custom QR code. Only present if account has a special agreement. | >= 002.60 |
webSocketUrl | String(2048) | URL of the websocket to use to monitor in real time the payment status. Transaction information are transmitted on the WebSocket when the payment has been processed by the shopper. | >= 002.60 |
transactionID | String(20) | The transaction ID of the Alipay transaction. Can be used to request the transaction information in poll mode if the WebSocket can not be used. | >= 002.60 |
transactionInfo | Object | In APP mode, if the result of the order is available immediately, the transaction information are returned directly in this field, no more action is needed in this case. | >= 002.60 |
rawRequest | String | In SDK mode only, this parameter contains the payment data that must be directly passed to the Alipay mobile SDK. | >= 002.60 |
Example JSON
{
"apiVersion":"002.60",
"code":"200",
"message":"Alipay order created successfully",
"qrCode":"iVBORw0KGgoAAAANSUhEUgAAASwAAAEsAQAAAABRBrPYAAABV0lEQVRREvTNaxmFyp4DGtSbKeOdA00UL2wGLXRnqHEAxLtmWOemLeypHGkPUM5YRG/RpK16yG7MZyN3u0ADLZS0rWsLkW07pxE7KeRfgYB1+2S2RammRbhuYc5ldRnBlZywxpStYSksmeCVnLUP4LNrNif5O1zOa5nB5DoEtMtmeaTYBsN9UZaGRf2PLYIfKUqZYl+8rQsUMr/aNtQib7x4U1wV4RmKxhPpeuarJ2N8kaVuEDmXLMbBNlyPhHIzIyMrIf2BsUMukXRTFJHwAAAABJRU5ErkJggg==",
"qrCodeUrl":"https://qr.alipay.com/paipai/show.htm?code=9446219319446735",
"webSocketUrl":"wss://connect2.payxpert.com/wsock/payment/1234567/alipay/direct/waitcallback/123456789123456789",
"transactionId":"1x3khr08jf-fbng"
}
Code samples
use PayXpert\Connect2Pay\Connect2PayClient;
use PayXpert\Connect2Pay\AliPayDirectProcessRequest;
// https://github.com/Textalk/websocket-php
use WebSocket\Client;
use PayXpert\Connect2Pay\TransactionAttempt;
$url = "https://connect2.payxpert.com";
// This will be provided once your account is approved
$originator = "000000";
$password = "Gr3atPassw0rd!";
$subscriptionID = "example"
$c2pClient = new Connect2PayClient($url, $originator, $password);
// Set all information for the payment
$c2pClient->setOrderID("ABC-123456");
$c2pClient->setPaymentMethod(Connect2PayClient::PAYMENT_METHOD_ALIPAY);
$c2pClient->setPaymentMode(Connect2PayClient::PAYMENT_MODE_SINGLE);
$c2pClient->setShopperID("1234567WX");
$c2pClient->setShippingType(Connect2PayClient::SHIPPING_TYPE_VIRTUAL);
// To charge €25.99
$c2pClient->setCurrency("EUR");
$c2pClient->setAmount(2599);
$c2pClient->setOrderDescription("Payment of €25.99");
$c2pClient->setShopperFirstName("John");
$c2pClient->setShopperLastName("Doe");
$c2pClient->setShopperAddress("NA");
$c2pClient->setShopperZipcode("NA");
$c2pClient->setShopperCity("NA");
$c2pClient->setShopperCountryCode("GB");
$c2pClient->setShopperPhone("+4712345678");
$c2pClient->setShopperEmail("shopper@example.com");
if ($c2pClient->preparePayment()) {
$resultCode = $c2pClient->getReturnCode();
echo "Payment prepare returned code " . $resultCode . "\n";
if ($resultCode == "200") {
echo "Processing Alipay direct transaction...\n";
$request = new AliPayDirectProcessRequest();
$request->mode = AliPayDirectProcessRequest::MODE_POS;
$customerToken = $c2pClient->getCustomerToken();
$response = $c2pClient->directAliPayProcess($customerToken, $request);
if ($response != null) {
echo "Result code: " . $response->getCode() . "\n";
echo "Result message: " . $response->getMessage() . "\n";
echo "Transaction ID: " . $response->getTransactionID() . "\n";
if ($response->getCode() == "200") {
echo "QR Code base64: " . $response->getQrCode() . "\n";
echo "QR Code URL: " . $response->getQrCodeUrl() . "\n";
echo "Web Socket URL: " . $response->getWebSocketUrl() . "\n";
echo "Listening on WebSocket...\n";
// Listen to the WebSocket
// /!\ This will block the current process
$client = new Client($response->getWebSocketUrl(), array("timeout" => 240));
try {
$transactionJson = $client->receive();
if ($transactionJson != null && strlen(trim($transactionJson)) > 0) {
echo "Received transaction status:\n";
$transaction = TransactionAttempt::getFromRawJson($transactionJson);
// Do something with the transaction result
}
} catch (Exception $e) {
echo "Error receiving information from the WebSocket: " . $e->getMessage() . "\n";
}
}
} else {
// Handle error
}
} else {
echo "No response received. Terminating\n";
}
}
} else {
echo "Return message is: " . $c2pClient->getReturnMessage() . "\n";
echo "Terminating\n";
}
// Instantiate the client and send the transaction information request
// Second argument is the originator ID, third one is the associated API key
Connect2payClient c2p = new Connect2payClient("https://connect2.payxpert.com", "123456", "GreatP4ssw0rd");
AliPayDirectProcessRequest request = new AliPayDirectProcessRequest();
AliPayDirectProcessResponse response = null;
try {
response = c2p.aliPayDirectProcess(request);
if (response != null) {
System.out.println(response.getCode());
System.out.println(response.getMessage());
if (ResultCode.SUCCESS.equals(response.getCode())) {
System.out.println(response.getTransactionId());
if (response.getWebSocketUrl() != null) {
System.out.println(response.getWebSocketUrl());
// Listen on the WebSocket to get the transaction result
} else {
TransactionAttempt transaction = response.getTransactionInfo();
if (transaction != null) {
System.out.println(transaction.getPaymentMethod());
System.out.println(transaction.getAmount());
System.out.println(response.getResultCode());
// ...
}
}
} else {
// Handle the error
}
}
} catch (Exception e) {
logger.error("Ooops, an error occurred getting account information: " + e.getMessage());
// Handle the error...
}
const paymentPage = require("payxpert")("123456", "GreatP4ssw0rd").connect2pay;
let requestCreatePaymentBody = {
"shippingType": "physical",
"paymentMethod": "alipay",
"paymentMode": "single",
"amount":1500,
"currency":"EUR",
"orderID":"NODEJS TEST"
};
let responseCreatePayment = await paymentPage.createPayment(body);
// Payment is prepared: now we can make ALIPAY direct payment call
let responseAliPayDirect = await paymentPage.createAliPayDirectPayment(responseCreatePayment.customerToken, { mode: "pos" });
if (responseAliPayDirect.code == "200") {
console.log("Payment prepared. QR code URL: " + responseAliPayDirect.qrCodeUrl);
console.log("Web socket URL: " + responseAliPayDirect.webSocketUrl);
} else {
console.log("Failed: " + responseAliPayDirect.message);
}
var client = new Connect2PayClient(OriginatorConfig.ORIGINATOR_ID, OriginatorConfig.ORIGINATOR_PASSWORD);
var request = client.NewRequestCreatePayment();
request.Data.orderID = "ABC-123456";
request.Data.paymentMethod = PaymentMethod.CREDIT_CARD;
request.Data.paymentMode = PaymentMode.SINGLE;
request.Data.shopperID = "RICH_SHOPPER";
request.Data.shippingType = ShippingType.VIRTUAL;
request.Data.operation = Operation.SALE;
request.Data.paymentMethod = PaymentMethod.ALIPAY;
request.Data.paymentMode = PaymentMode.SINGLE;
request.Data.amount = 1500; // 15 EUR
request.Data.currency = "EUR";
request.Data.orderDescription = "Payment of €15.00";
request.Data.shopperFirstName = "RICH";
request.Data.shopperLastName = "SHOPPER";
request.Data.shopperAddress = "NA";
request.Data.shopperZipcode = "999111";
request.Data.shopperCity = "NA";
request.Data.shopperCountryCode = "GB";
request.Data.shopperPhone = "123-456";
request.Data.shopperEmail = "test@test.test";
request.Data.ctrlCustomData = "Give that back to me please !!";
request.Data.ctrlRedirectURL = "https://merchant.example.com/payment/redirect";
request.Data.ctrlCallbackURL = "https://merchant.example.com/payment/callback";
if (request.Data.Validate())
{
var response = await request.Send();
if (response.IsSuccessfull())
{
Console.WriteLine("Request executed successfully");
Console.WriteLine("Merchant token: " + response.merchantToken);
Console.WriteLine("Customer redirect URL: " + request.getCustomerRedirectURL());
Console.WriteLine("Preparing ALIPAY direct payment...");
var requestAliPayDirect = client.NewRequestAliPayDirect(response.customerToken);
requestAliPayDirect.Data.mode = AliPayDirectMode.POS;
var responseAliPayDirect = await requestAliPayDirect.Send();
if (responseAliPayDirect.IsSuccessfull())
{
Console.WriteLine("ALIPAY direct request prepared successfully");
Console.WriteLine("ALIPAY QR code URL: " + responseAliPayDirect.qrCodeUrl);
} else {
Console.WriteLine("ALIPAY direct request failure: " + responseAliPayDirect.code + ": " + responseAliPayDirect.message);
}
} else {
Console.WriteLine("Request failure: " + response.code + ": " + response.message);
}
}