> ## Documentation Index
> Fetch the complete documentation index at: https://curlec.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Alipay+ S2S Integration

> Accept payments from overseas customers paying with Alipay+ wallets such as GCash, DANA and TrueMoney using Razorpay Curlec S2S integration.

Use this guide to accept [Alipay+](https://curlec.com/docs/payments/payment-methods/wallets/alipay-plus.md) payments on your existing Server-to-Server (S2S) integration. Alipay+ wallets use the same wallet flow as any other wallet on S2S: you create an order, create a payment with `method` as `wallet` and the Alipay+ wallet code in `wallet`, and redirect your customer to approve the payment.

> [!NOTE]
>
> **Early Access**
>
> Alipay+ on S2S is available on request. Contact your account manager or our [Support team](https://curlec.com/support/) to have it enabled on your account before you start. Standard Checkout does not need this step.

## Prerequisites

* **Existing S2S integration:** an active [S2S JSON integration](https://curlec.com/docs/payments/payment-gateway/s2s-integration) with Razorpay Curlec, including [API keys](https://curlec.com/docs/api/authentication.md#generate-api-keys).
* **Alipay+ enabled for S2S:** Alipay+ is not enabled by default. Tell us which wallets you want to offer and we will enable them. Before we switch it on, we register your business with Alipay+, so enablement is not instant. You need no agreement of your own with Alipay+ or with any individual wallet.

## Wallet Codes

Pass one of these codes in the `wallet` field. Only the wallets enabled on your account are accepted.

| Wallet | Country or Region | Wallet Code |
| - | - | - |
| GCash | Philippines | `gcash` |
| DANA | Indonesia | `dana` |
| TrueMoney | Thailand | `truemoney` |
| Alipay | China | `alipay` |
| AlipayHK | Hong Kong | `alipayhk` |
| Kakao Pay | South Korea | `kakaopay` |
| Rabbit LINE Pay | Thailand | `rabbitlinepay` |

Alipay+ is for overseas customers only. Your customer pays in their wallet's currency, Alipay+ handles the currency conversion, and you create the order and are settled in Malaysian ringgit (`MYR`).

## Integration Steps

**1.1** [Check the Wallets Enabled on Your Account](#1-1-check-the-wallets-enabled-on-your-account)

**1.2** [Create an Order](#1-2-create-an-order)

**1.3** [Create a Payment](#1-3-create-a-payment)

**1.4** [Redirect Your Customer](#1-4-redirect-your-customer)

**1.5** [Confirm the Payment Status](#1-5-confirm-the-payment-status)

**1.6** [Verify Payment Signature](#1-6-verify-payment-signature)

### 1.1 Check the Wallets Enabled on Your Account

Use the Methods API to check which Alipay+ wallets are enabled on your account, and show only those to your customer. The response lists every wallet enabled on your account, including Malaysian wallets such as Touch 'n Go. The Alipay+ wallets are the codes listed in [Wallet Codes](#wallet-codes), and the sample below shows only those.

```bash Request theme={null}
curl --location --request GET 'https://api.razorpay.com/v1/methods?key_id={MERCHANT_API_KEY}'
```

```json Response theme={null}
{
  "entity": "methods",
  "wallet": {
    "gcash": true,
    "dana": true,
    "alipay": true,
    "alipayhk": true
  }
}
```

### 1.2 Create an Order

Create an order in `MYR` for every payment. The `order_id` in the response ties the payment to the order.

`POST /orders`

```bash Curl theme={null}
curl -X POST https://api.razorpay.com/v1/orders \
-u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \
-H 'content-type: application/json' \
-d '{
  "amount": 5000,
  "currency": "MYR",
  "receipt": "receipt#1111"
}'
```

```json Response theme={null}
{
  "id": "order_NUJs9C1Luflzts",
  "entity": "order",
  "amount": 5000,
  "amount_paid": 0,
  "amount_due": 5000,
  "currency": "MYR",
  "receipt": "receipt#1111",
  "status": "created",
  "attempts": 0,
  "notes": [],
  "created_at": 1727000000
}
```

#### Request Parameters

`amount` *mandatory*
: `integer` The payment amount in the smallest currency subunit. For example, to charge RM 50.00, pass `5000`.

`currency` *mandatory*
: `string` The currency of the order. Here, it must be `MYR`.

`receipt` *optional*
: `string` Your receipt ID for this order. Maximum length is 40 characters.

`notes` *optional*
: `json object` Key-value pairs to store additional information about the order. Maximum 15 pairs, 256 characters each.

Know more about the [Orders API](https://curlec.com/docs/api/orders/create.md) and the [Orders entity](https://curlec.com/docs/api/orders/entity.md).

### 1.3 Create a Payment

Create a payment against the order, with `method` as `wallet` and `wallet` as the Alipay+ wallet your customer chose.

`POST /payments/create/json`

```bash Curl theme={null}
curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \
-X POST https://api.razorpay.com/v1/payments/create/json \
-H "content-type: application/json" \
-d '{
  "amount": 5000,
  "currency": "MYR",
  "order_id": "order_NUJs9C1Luflzts",
  "email": "customer@example.com",
  "contact": "+639171234567",
  "method": "wallet",
  "wallet": "gcash",
  "callback_url": "https://example.com/payment/callback"
}'
```

```json Response theme={null}
{
  "razorpay_payment_id": "pay_O0NSBQgY0BbC4b",
  "next": [
    {
      "action": "redirect",
      "url": "https://api.razorpay.com/v1/payments/O0NSBQgY0BbC4b/authenticate"
    }
  ]
}
```

#### Request Parameters

`amount` *mandatory*
: `integer` The payment amount in the smallest currency subunit. It must match the order amount.

`currency` *mandatory*
: `string` Here, it must be `MYR`.

`order_id` *mandatory*
: `string` The order ID returned in [step 1.2](#1-2-create-an-order).

`email` *mandatory*
: `string` Email address of the customer.

`contact` *mandatory*
: `string` Phone number of the customer, including the country code.

`method` *mandatory*
: `string` Here, it must be `wallet`.

`wallet` *mandatory*
: `string` The Alipay+ wallet to charge the customer through. Possible values: `gcash`, `dana`, `truemoney`, `alipay`, `alipayhk`, `kakaopay` and `rabbitlinepay`. See [Wallet Codes](#wallet-codes).

`callback_url` *mandatory*
: `string` The URL your customer returns to after they complete or leave the payment.

#### Response Parameters

`razorpay_payment_id`
: `string` Unique identifier of the payment. Store it to check the payment status later.

`next`
: `array` The next step to continue the payment.

`action`
: `string` Here, it is `redirect`.

`url`
: `string` The URL to redirect your customer to so that they can approve the payment.

### 1.4 Redirect Your Customer

Redirect your customer to the `url` in `next`. Alipay+ hosts the approval:

* **On web**, your customer sees the Alipay+ payment page and approves the payment in their wallet.
* **On mobile**, your customer may also be shown the payment page in a browser rather than being taken straight into the wallet app. The payment works either way.

> [!WARNING]
>
> **Watch Out!**
>
> Your customer has **12 minutes** to approve the payment. After that, Alipay+ cancels it. Create a new payment on the same order if your customer wants to try again — do not reuse the expired link.

### 1.5 Confirm the Payment Status

After approval, Razorpay Curlec confirms the result with Alipay+ before it authorises and captures the payment, so the final status can arrive shortly after your customer returns to your `callback_url`. Do not treat the redirect to your `callback_url` alone as confirmation. Confirm the status using one of these:

* **Webhooks (recommended):** subscribe to `payment.authorized`, `payment.captured`, `payment.failed` and `order.paid`. Know more about [payment webhooks](https://curlec.com/docs/webhooks/payments.md).
* **Fetch the payment:** call the [Fetch a Payment API](https://curlec.com/docs/api/payments/fetch-with-id.md) with the `razorpay_payment_id` and check that `status` is `captured`.

A payment that stays in `created` has not been approved yet. Do not ship the order until the payment is `captured`.

### 1.6 Verify Payment Signature

When your customer returns to your `callback_url` after a successful payment, the request contains `razorpay_payment_id`, `razorpay_order_id` and `razorpay_signature`. Verify the signature before you update the order in your system.

Create a string from the `order_id` you created in step 1.2 and the `razorpay_payment_id`, separated by `|`. Hash it using HMAC SHA256 with your API key secret, and compare it with `razorpay_signature`.

```
generated_signature = hmac_sha256(order_id + "|" + razorpay_payment_id, secret);

if (generated_signature == razorpay_signature) {
    payment is successful
}
```

## Refunds

You can refund Alipay+ payments in full or in part using the [Refunds API](https://curlec.com/docs/api/refunds.md).

## Frequently Asked Questions

> [accordion] Can I test Alipay+ on S2S before going live?
>
> A test mode flow is not available for Alipay+ today. Contact our [Support team](https://curlec.com/support/) and we will confirm what is possible for your account.

> [accordion] Do I need to change my integration when a new wallet joins Alipay+?
>
> Only to show the new wallet to your customers. Once we enable it on your account, it appears in the Methods API response, and you pass its code in the `wallet` field like any other Alipay+ wallet.

> [accordion] Can I take recurring payments with Alipay+?
>
> No. Alipay+ is for one-time payments only.

### Related Information

* [Alipay+](https://curlec.com/docs/payments/payment-methods/wallets/alipay-plus.md)
* [S2S Integration: Wallets](https://curlec.com/docs/payments/payment-gateway/s2s-integration/payment-methods/wallet)
* [About Wallets](https://curlec.com/docs/payments/payment-methods/wallets)
