### Return Example

Source: https://alchemypay.readme.io/docs/webhook-for-orders

This section shows an example of a successful API response, detailing the fields and their expected values.

```APIDOC
## GET /payment/status

### Description
This endpoint returns the status of a payment transaction.

### Method
GET

### Endpoint
/payment/status

### Query Parameters
- **orderNo** (string) - Required - The unique order number for the payment.

### Response
#### Success Response (200)
- **applyFee** (string) - The applied fee for the transaction.
- **cardAmount** (string) - The amount paid using the card.
- **cardCurrency** (string) - The currency of the card payment.
- **cardId** (string) - The ID of the card used.
- **cardNumber** (string) - The masked card number.
- **cardType** (string) - The type of card used.
- **cryptoAddress** (string) - The cryptocurrency address for the transaction (if applicable).
- **cryptoCurrency** (string) - The cryptocurrency used for the transaction (if applicable).
- **cryptoCurrencyExchangeRate** (string) - The exchange rate for the cryptocurrency (if applicable).
- **currencyExchangeRate** (string) - The exchange rate between currencies.
- **deliveryFee** (string) - The delivery fee for the transaction.
- **email** (string) - The email address associated with the transaction.
- **failReason** (string) - The reason for payment failure (if applicable).
- **network** (string) - The network used for cryptocurrency transactions (if applicable).
- **orderAmount** (string) - The total order amount.
- **orderNo** (string) - The unique order number.
- **orderTime** (string) - The time the order was placed.
- **orderType** (string) - The type of order.
- **paymentAmount** (string) - The amount paid.
- **rechargeFee** (string) - The recharge fee.
- **rechargeMarkup** (string) - The recharge markup.
- **status** (string) - The status of the order (e.g., "SUCCESS", "FAILED").
- **voucherCode** (string) - The voucher code used (if applicable).

#### Response Example
```json
{
    "applyFee": "0",
    "cardAmount": "55",
    "cardCurrency": "EUR",
    "cardId": "1232330814012345678",
    "cardNumber": "5554748800912345",
    "cardType": "2",
    "cryptoAddress": "",
    "cryptoCurrency": "USDT",
    "cryptoCurrencyExchangeRate": "1",
    "currencyExchangeRate": "1.092759",
    "deliveryFee": "0",
    "email": "dfghjdfgha@gmail.com",
    "failReason": "",
    "network": "TRX",
    "orderAmount": "61.91",
    "orderNo": "100217231874691123456",
    "orderTime": "2024-08-09 15:11:09",
    "orderType": "2",
    "paymentAmount": "61.91",
    "rechargeFee": "0.72122094",
    "rechargeMarkup": "0.99",
    "status": "SUCCESS",
    "voucherCode": ""
}
```

## Note
For more error codes, please refer to the error code description on the homepage.
```

--------------------------------

### Off-Ramp Response Parameters Example

Source: https://alchemypay.readme.io/docs/create-order-3

This example shows a successful response for an off-ramp transaction. It provides the order number and the received address for the cryptocurrency.

```json
{
    "success": true,
    "returnCode": "0000",
    "returnMsg": "SUCCESS",
    "extend": "",
    "data": {
        "orderNo": "139***",
        "receivedAddress": "0xcbca***"
    }
}
```

--------------------------------

### On-Ramp Response Parameters Example

Source: https://alchemypay.readme.io/docs/create-order-3

This example shows a typical successful response for an on-ramp transaction. It includes order details and a web URL for completing the payment.

```json
{
    "success": true,
    "returnCode": "0000",
    "returnMsg": "SUCCESS",
    "extend": "",
    "data": {
        "orderNo": "onramp100001",
        "webUrl": "https://www.google.com"
    }
}
```

--------------------------------

### Off-Ramp Request Parameters Example

Source: https://alchemypay.readme.io/docs/create-order-3

This example illustrates the parameters required for an off-ramp (sell) transaction. It specifies the cryptocurrency to sell, amount, fiat currency, and callback URL.

```json
{
    "side": "SELL",
    "merchantOrderNo": "mer100001",
    "cryptoCurrency": "USDT",
    "network": "ETH",
    "amount": "123.123", // Quantity of crypto being sold
    "alpha2": "US",
    "fiatCurrency": "USD",
    "payWayCode": "10001",
    "userAccountId": "12312",
    "orderType": 6, // Fixed to 6
    "callbackUrl": "http://payment.jyoumoney.com/alchemyRamp/pay/callback?tradeNo=***"
}
```

--------------------------------

### Webhook Parameter Example

Source: https://alchemypay.readme.io/docs/webhook-for-refund-order

This example demonstrates the structure and fields included in a webhook notification from AlchemyPay, particularly for refund events.

```APIDOC
## Webhook Parameter Example

### Description
This example showcases the JSON payload structure for a webhook event, specifically illustrating the details provided for a refund operation initiated by the merchant.

### Method
POST

### Endpoint
`/webhooks` (example endpoint, actual endpoint may vary)

### Parameters
#### Request Body
- **faitAmount** (string) - The amount in fiat currency.
- **fiatCurrency** (string) - The currency code for the fiat amount (e.g., USD).
- **hxAddress** (string) - The Hx address associated with the transaction.
- **merchantOrderNo** (string) - The merchant's unique order number.
- **orderStatus** (string) - The current status of the order (e.g., COMPLETED).
- **paymentOrderNo** (string) - AlchemyPay's unique payment order number.
- **refundNetwork** (string) - The blockchain network used for the refund (e.g., TRX).
- **refundOrderNo** (string) - The unique order number for the refund.
- **refundToken** (string) - The token used for the refund (e.g., USDT).
- **refundType** (string) - The type of refund (e.g., MERCHANT_APPROVE_REFUND).
- **sign** (string) - The signature for verifying the webhook authenticity.
- **tokenAmount** (string) - The amount in the token currency.

### Request Example
```json
{
      "faitAmount": "9.90000000",
      "fiatCurrency": "USD",
      "hxAddress": "05b40909e7dd03cd0c1303c1e740edaa682f15ea7ed4af3bca5adffbe10da277",
      "merchantOrderNo": "17304484880000",
      "orderStatus": "COMPLETED",
      "paymentOrderNo": "300317304490044680240",
      "refundNetwork": "TRX",
      "refundOrderNo": "300217304490044230335",
      "refundToken": "USDT",
      "refundType": "MERCHANT_APPROVE_REFUND",
      "sign": "C2A745E335DE17F3D0C6F2920CD62A96F6F8445E692ED5CDE7EED35BF8AF7B2BC298CC2440700A6F3323A71D18C5200B793286B340B8AB6B67F99424C1B3A154",
      "tokenAmount": "8.40000000"
}
```

### Response
#### Success Response (200 OK)
Typically, a successful webhook receipt doesn't require a complex response body. An HTTP 200 OK status is usually sufficient to acknowledge receipt.

#### Response Example
```json
{
  "message": "Webhook received successfully"
}
```
```

--------------------------------

### Example of Usage (holderQuery)

Source: https://alchemypay.readme.io/docs/api-integration-4

Provides a cURL example for invoking the holderQuery endpoint, demonstrating the required parameters and content type.

```APIDOC
## Example of Usage

> Note that the format should be application/x-www-form-urlencoded instead of application/json.

```bash
curl -X POST https://test-physicalcard-api.alchemypay.org/api/mastercard/holderQuery.html \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "agentId=888666000100201&reqData=2%2FCgBnwbtXQRR2XVmLu9uOiBCfjnd1pwq59LtPhufF6VtjbKcArfHE9Cqff575EFbIEBanPKlXbilnJj2Gz4AnEs1BOZOUEO85UIcD7YBBXdt1BC3vX8hzWXrsnPbC1ZW4589r7B40h0lL9NAOjs%2BJaDIN3nmpdqvFHJ4hF1rb0%3D&signature=e5c3ca8eba4de85f44262f8d34ac21ee"
```
```

--------------------------------

### API Signature Generation Example

Source: https://alchemypay.readme.io/docs/about-the-sign-3

Demonstrates the process of generating an API signature using example request parameters. It shows the intermediate string concatenation and the final SHA-512 hashed signature.

```JSON
{
    "appId": "TEST000001",
    "sign": "TEST000001",
    "merchantOrderNo": "11126",
    "userId": "123456789@qq.com",
    "orderAmount": "1000",
    "payCurrency": "USD",
    "paymentTokens": "USDT,ETH",
    "paymentExchange": "16f021b0-f220-4bbb-aa3b-82d423301957,9226e5c2-ebc3-4fdd-94f6-ed52cdce1420"
}
```

```Text
appId=TEST000001&merchantOrderNo=11126&orderAmount=1000&payCurrency=USD&paymentExchange=16f021b0-f220-4bbb-aa3b-82d423301957,9226e5c2-ebc3-4fdd-94f6-ed52cdce1420&paymentTokens=USDT,ETH&userId=505884978@qq.com&key=**************0b5nCak
```

```Text
3962E8FF2ABD24B806D744C6630B95A05855A2AB86944CCF52009D6E2582787EB0F34CFF323843DDA55B148D770390598AF335DDBECC61D702AA1A87EE93D
```

--------------------------------

### On-Ramp Request Parameters Example

Source: https://alchemypay.readme.io/docs/create-order-3

This example demonstrates the required and optional parameters for an on-ramp transaction request. It includes details for cryptocurrency, merchant order, payment method, and user information.

```json
{
    "side": "BUY",
    "merchantOrderNo": "mer100001",
    "cryptoCurrency": "USDT",
    "address": "TSx82tWNWe5Ns6t***",
    "network": "TRX",
    "memo": "123123", //Optional
    "fiatCurrency": "USD",
    "amount": "100",
    "orderType": "4", // Fixed to 4
    "payWayCode": "10001",
    "userAccountId": "12312", // Optional, must fill in for card payment and account
    "redirectUrl": "http://google.com/alchemy/payResultPage/DZ02207121427022754",
    "callbackUrl": "http://google.com/alchemyRamp/pay/callback"
}
```

--------------------------------

### Webhook Example - COMPLETED

Source: https://alchemypay.readme.io/docs/webhook-for-order-status

Example of a webhook notification when an order status is COMPLETED.

```APIDOC
## Webhook Example - COMPLETED

### Description

This is an example of the JSON payload received via webhook when an order status changes to COMPLETED.

### Response Example

```json
{
    "fee": "2",
    "hxAddress": "2b04aa547740d8de8d442bc1827457b3e9bf4551234567893c319",
    "merchantOrderNo": "to_4bc9603bc5c123456",
    "orderAmount": "100",
    "orderCurrency": "USD",
    "orderNo": "3002172361782345678",
    "orderStatus": "COMPLETED",
    "payCryptoCurrency": "USDT",
    "payCryptoNetwork": "TRX",
    "payCryptoRate": "1",
    "payCryptoVolume": "102",
    "settlementAmount": "100",
    "settlementCurrency": "USD",
    "sign": "C615A4F6436CAA3C5B74AA80AF0CF08D342E7C49D0164765D3563EC3E3E61F889E9B46BB1E6F1EEEB28280DA233B81E31591C8B1A33C0EE7969CD3",
    "userId": "u_dabd123456"
}
```
```

--------------------------------

### On-Ramp Response Parameters Example (PayID)

Source: https://alchemypay.readme.io/docs/create-order-3

This example demonstrates the response for an on-ramp transaction using the PayID payment method. It includes the order number, reference number, and PayID.

```json
{
    "success": true,
    "returnCode": "0000",
    "returnMsg": "SUCCESS",
    "extend": "",
    "data": {
        "orderNo": "1393139009753305088",
        "referenceNumber": "522***",
        "payId": "abc123@email.com"
    },
    "traceId": "6870c3c88dd61f975f3359b54ad54fb2"
}
```

--------------------------------

### On-Ramp Response Parameters Example (QRIS)

Source: https://alchemypay.readme.io/docs/create-order-3

This example illustrates the response for an on-ramp transaction using the QRIS payment method. It provides an order number and a QR code string.

```json
{
    "success": true,
    "returnCode": "0000",
    "returnMsg": "SUCCESS",
    "extend": "",
    "data": {
        "orderNo": "1393135310930825216",
        "qrCode": "00020101021226610016ID.CO.SHOPEE.****"
    },
    "traceId": "6870c056ee9707c8bcbad2adf87ddda3"
}
```

--------------------------------

### Request Parameter Example - JSON

Source: https://alchemypay.readme.io/docs/create-order-v2

An example JSON object demonstrating the structure and required fields for a payment request. This includes details like appId, callbackURL, order details, and signature.

```json
{
    "appId": "TEST000001",
    "callbackURL": "https://90fc-111-10-154.ngrok-free.app/v1/xxxxx",
    "expiredTime": "60",
    "merchantOrderNo": "17236123450000",
    "orderAmount": "100",
    "orderModel": "ORDER",
    "payCurrency": "USD",
    "paymentTokens": "ETH",
    "redirectURL": "https://50xxxxx832.vicp.fun/platform/xxxxx",
    "sign": "07572BA8F945685E6BB57FC21FDE74E7217A015E00FD56176F3A500465817B33FAC086DA7887AC266BA8518960F0FE208DE1A8E105978B185A8D136DD0F6",
    "userId": "xxxxxxxe@alchemytech.io"
}
```

--------------------------------

### On-Ramp Response Parameters Example (VA)

Source: https://alchemypay.readme.io/docs/create-order-3

This example shows the response for an on-ramp transaction using a Virtual Account (VA) payment method. It includes the order number, bank name, and account number.

```json
{
    "success": true,
    "returnCode": "0000",
    "returnMsg": "SUCCESS",
    "extend": "",
    "data": {
        "orderNo": "1393135564782686208",
        "bankName": "VA BRI",
        "accountNumber": "13033***"
    },
    "traceId": "6870c0931309ecd3e4d7f2ffc2f4b456"
}
```

--------------------------------

### AlchemyPay Request Parameters Example (JSON)

Source: https://alchemypay.readme.io/docs/native-api-integration-2

An example JSON object representing a payment request to AlchemyPay. It includes essential details like appId, merchantOrderNo, orderAmount, payCurrency, and callbackURL.

```json
{
    "appId":"TEST000001",
    "sign":"TEST000001",
    "merchantOrderNo":"131222222222344345",
    "userId":"e383id83j@gmail.com",
    "orderAmount":"1",
    "payCurrency":"USDT",
    "paymentNetworks":"ETH",
    "paymentTokens":"USDT",
    "userIp":"106.37.115.196",
    "expiredTime":"7200",
    "callbackURL":"http://test.crypto.payment/open/api/callback"
}
```

--------------------------------

### Request Body Example for Get Token (Email)

Source: https://alchemypay.readme.io/docs/get-token

Example JSON payload for the POST request to obtain a user token using the user's email address. This is a conditional mandatory parameter.

```json
{
	"email": "test@gmail.com"
}
```

--------------------------------

### Response Example for Get Token (UID)

Source: https://alchemypay.readme.io/docs/get-token

Example JSON response after successfully obtaining a user token using the UID parameter. Includes success status, return codes, and the generated access token.

```json
{
    "success": true,
    "returnCode": "0000",
    "returnMsg": "SUCCESS",
    "extend": "",
    "data": {
        "accessToken": "ACH8658667838@ACH@0sf2EDon8eujsasbMDo3g==@PAY@XXpkhtp3Oau+DfgOqwUNUEk1Ijdx7175Cpbcw2sm8hQ=@IO@oKMVGvEf/W9C3QD1/eEsRraWzYaQPJxS9L96NSQWCOheWzsOeRSBmZfxj8Vdu5kpLQy+pymyVbSdtFETC2Znwg==",
        "id": "G0sf2Eon8eujsasbMDo3g=="
    },
    "traceId": "67ff761516e999cf1038d8a2f71e6de7"
}
```

--------------------------------

### Response Example for Get Token (Email)

Source: https://alchemypay.readme.io/docs/get-token

Example JSON response after successfully obtaining a user token using the email parameter. Includes success status, return codes, and the generated access token.

```json
{
    "success": true,
    "returnCode": "0000",
    "returnMsg": "SUCCESS",
    "extend": "",
    "data": {
        "id": "kklzDn3K/BvuSXs559OQfQ==",
        "accessToken": "ACH8945766425@ACH@kklzDn3K/BvuSXs559OQfQ==@PAY@cwqgsiyILMYNuMjhxhaQLpCX1hnntIqfL+V7uEqNu6I=@IO@g5aBrOrzxrfzsqs8W0cKR4VBugBZBSH5gYLOoL1eHICLR3GTygMCaCN3RvIMaeOUmy9PAVmFImjz+4uXR1MpRg==",
        "email": "cwqgsiyILMYNuMjhxhaQLpCX1hnntIqfL+V7uEqNu6I="
    },
    "traceId": "642e6990f3481462c6185b310ba2120b"
}
```

--------------------------------

### Request Body Example for Get Token (UID)

Source: https://alchemypay.readme.io/docs/get-token

Example JSON payload for the POST request to obtain a user token using a user's unique identifier (UID). This is a conditional mandatory parameter.

```json
{
	"uid": "1234567xxxxx"
}
```

--------------------------------

### Get Card Details Request Example (JSON)

Source: https://alchemypay.readme.io/docs/api-for-virtual-card-deposit-recharge-copy

Example of a POST request to the /open/api/card/info endpoint to retrieve card details. This request requires the 'cardId' and optionally accepts a 'currency' parameter.

```json
{
    "cardId": "c_xxxxxxxxxxx"
}
```

--------------------------------

### Get Card Activation Link Example (JSON)

Source: https://alchemypay.readme.io/docs/get-card-activate-link

This code snippet demonstrates a successful response when requesting a virtual card activation link from the AlchemyPay API. It includes the activation link, which is valid for 24 hours, along with other status and tracing information.

```json
{
    "code":"0",
    "msg":"成功",
    "model":{
      "activeLink":"http://www.***.com/login?wallet=8012&token=eyJraWQiOiIybWE0ZW51MWtkdnc1Ym85eHNmcGkzZ2NqenJ0NnE3OHlsMGgiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI3NG8E2ggqX5NUIoAu5wQgvrLqLaiRn7n7rKgdrFtIVNsQUjfnlc5_uZewYn_ZaVwu7wj78_5UBNy59nJtQGyPrFR2owAXY70HA",
    },
    "traceId":"665597457b9b37cb000187a035002030",
    "success":true,
    "error":false
}
```

--------------------------------

### Initialize AlchemyPay iOS SDK

Source: https://alchemypay.readme.io/docs/ios-sdk

Demonstrates how to import and initialize the AlchemyPay SDK in Swift. It covers setting the debug mode, environment (sandbox/production), and rendering options (WebViewOverlay/InAppBrowser). The initialization requires a configuration object with specific parameters.

```swift
import RampPaySdk

let config = RampPaySdkConfig(
    debug: true, // true or false
    environment: RampPayEnvironment.sandbox, // Sandbox or Production
    params: nil // Concatenated URL parameters
)

let rampPaySdk = RampPaySdk(config: config)
rampPaySdk.show(mode: RampPayRenderingOption.webviewoverlay) // WebViewOverlay or InAppBrowser
```

--------------------------------

### Get User Token API Request Example (JSON)

Source: https://alchemypay.readme.io/docs/fetch-token

This code snippet demonstrates the JSON payload required for the 'getToken' API request. It includes the mandatory 'email' field for identifying the end-user. This is used in conjunction with header parameters like appId, timestamp, and sign.

```json
{
    "email": "test@gmail.com"
}
```

--------------------------------

### Example Login-Free Link with Token

Source: https://alchemypay.readme.io/v4.0.2/docs/login-free-instructions

This is an example of a URL that incorporates the generated token. The token must be URL encoded and appended to the base URL with the 'token' parameter name to enable login-free access.

```url
https://ramptest.alchemypay.org/?crypto=USDT&network=BSC&appId=f83Is2y7L425rxl8&token=ACH8945766425%40ACH%40kklzDn3K%2FBvuSXs559OQfQ%3D%3D%40PAY%40cwqgsiyILMYNuMjhxhaQLpCX1hnntIqfL%2BV7uEqNu6I%3D%40IO%40g5aBrOrzxrfzsqs8W0cKR4VBugBZBSH5gYLOoL1eHICLR3GTygMCaCN3RvIMaeOUmy9PAVmFImjz%2B4uXR1MpRg%3D%3D#/index
```

--------------------------------

### Install ACHRampRiskSDK JavaScript SDK

Source: https://alchemypay.readme.io/docs/get-cookie-for-credit-card-payment

This snippet shows how to include the ACHRampRiskSDK JavaScript SDK in your project by adding a script tag. Ensure the path to the SDK file is correct.

```html
<script src="path/to/your/js/achramp-risk-sdk.min.js"></script>
```

--------------------------------

### Successful Response Example

Source: https://alchemypay.readme.io/docs/query-order

An example of a successful API response, detailing a completed payment transaction.

```APIDOC
### Response Parameter Example: SUCCESS

```json
{
    "address": "T9ys1EqRenWmUGCXx4ASDFGHJY1CtA",
    "fee": "2",
    "hxAddress": "2b04aa547740d8de8d442bc18212345678b0010d6658379bf3c319",
    "merchantOrderNo": "to_4bc9603b12345685",
    "orderAmount": "100",
    "orderCurrency": "USD",
    "orderNo": "300217231234569729",
    "orderStatus": "COMPLETED",
    "payCryptoCurrency": "USDT",
    "payCryptoNetwork": "TRX",
    "payCryptoRate": "1",
    "payCryptoVolume": "102",
    "payFiatRate": "1",
    "settlementAmount": "100",
    "settlementCurrency": "USD",
    "sign": "C615A4F6436CAA308D342E7C49D0164765D3563EC3E3E61F889E9B46BB1E6F1EEEB28280DA233B81E31591C8B1A33C0EE7969CD3",
    "userId": "u_dabd12345647"
}
```
```

--------------------------------

### AlchemyPay Account Response Example (JSON)

Source: https://alchemypay.readme.io/docs/payment-method-form-query

This JSON example shows the response structure for account-related operations. It details fields for submitting account forms and includes data sources for fields like country, account type, and bank information.

```json
{
    "success": true,
    "returnCode": "0000",
    "returnMsg": "SUCCESS",
    "extend": "",
    "data": {
        "fields": [
            {
                "fieldName": "accountNo",
                "fieldType": "string",
                "regex": "^\\d{9,16}$",
                "formElement": "input"
            },
            {
                "fieldName": "country",
                "fieldType": "string",
                "regex": "",
                "formElement": "select",
                "dataSourceKey": "countryList"
            },
            {
                "fieldName": "accountType",
                "fieldType": "string",
                "regex": "",
                "formElement": "select",
                "dataSourceKey": "accountTypeList"
            },
            {
                "fieldName": "bankId",
                "fieldType": "string",
                "regex": "",
                "formElement": "select",
                "dataSourceKey": "bankList"
            },
            {
                "fieldName": "bankName",
                "fieldType": "string",
                "regex": "",
                "formElement": "select",
                "dataSourceKey": "bankList"
            }
        ],
        "dataSource": {
            "bankList": [
                {
                    "locationId": "4172",
                    "bankId": "4172",
                    "bankName": "DBS Bank Ltd, HK Branch",
                    "bankBranch": "Hong Kong DBS Bank Ltd, HK Branch",
                    "address": "Hong Kong DBS Bank Ltd, HK Branch",
                    "city": "Hong Kong",
                    "currency": "HKD",
                    "countryCode": "HK",
                    "country": "HK",
                    "transactionType": "B2C",
                    "channelCode": "57"
                },
                {
                    "locationId": "4173",
                    "bankId": "4173",
                    "bankName": "The Shizuoka Bank, Ltd.",
                    "bankBranch": "Hong Kong The Shizuoka Bank, Ltd.",
                    "address": "Hong Kong The Shizuoka Bank, Ltd.",
                    "city": "Hong Kong",
                    "currency": "HKD",
                    "countryCode": "HK",
                    "country": "HK",
                    "transactionType": "B2C",
                    "channelCode": "57"
                },
                {
                    "locationId": "4174",
                    "bankId": "4174",
                    "bankName": "The Hachijuni Bank Ltd",
                    "bankBranch": "Hong Kong The Hachijuni Bank Ltd",
                    "address": "Hong Kong The Hachijuni Bank Ltd",
                    "city": "Hong Kong",
                    "currency": "HKD",
                    "countryCode": "HK",
                    "country": "HK",
                    "transactionType": "B2C",
                    "channelCode": "57"
                }
            ],
            "accountTypeList": [
                {
                    "fieldName": "accountType",
                    "value": "SAVINGS",
                    "desc": "savings"
                },
                {
                    "fieldName": "accountType",
                    "value": "CHECKING",
                    "desc": "checking"
                },
                {
                    "fieldName": "accountType",
                    "value": "DEPOSIT",
                    "desc": "deposit"
                }
            ]
        }
    }
}
```

--------------------------------

### GET /open/api/card/findLink

Source: https://alchemypay.readme.io/docs/get-card-activate-link

Retrieves a virtual card activation link. This link is valid for 24 hours.

```APIDOC
## GET /open/api/card/findLink

### Description
Retrieves a virtual card activation link. This link is valid for 24 hours.

### Method
GET

### Endpoint
`/open/api/card/findLink`

### Parameters

#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **success** (boolean) - Success flag
- **error** (boolean) - Error flag
- **code** (long) - Return code
- **msg** (string) - Return information
- **traceId** (string) - traceId
- **model** (object) - Return content
  - **activeLink** (string) - Card activation link (Valid for 24 hours)

#### Response Example
```json
{
    "code":"0",
    "msg":"成功",
    "model":{
      "activeLink":"http://www.***.com/login?wallet=8012&token=eyJraWQiOiIybWE0ZW51MWtkdnc1Ym85eHNmcGkzZ2NqenJ0NnE3OHlsMGgiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI3NG8E2ggqX5NUIoAu5wQgvrLqLaiRn7n7rKgdrFtIVNsQUjfnlc5_uZewYn_ZaVwu7wj78_5UBNy59nJtQGyPrFR2owAXY70HA",
    },
    "traceId":"665597457b9b37cb000187a035002030",
    "success":true,
    "error":false
}
```
```

--------------------------------

### Response Example (holderQuery)

Source: https://alchemypay.readme.io/docs/api-integration-4

Illustrates a typical success response from an API call, including the response code, message, and encrypted response data.

```APIDOC
## Response Example

> Normally, all interface data needs to be decrypted using an RSA private key when receiving data from the server.

```json
{
  "respCode": "00",
  "respMsg": "",
  "respData": "nnTq5O+k89BsneEN1+SUKxj6PlNSsBzeF29IeEkNQjWrRATjW+dtYPONKFO9YfG5dlLg1qZH5PBRbEWB44Q9wmvT5PLoJNdM5Uk1zhhLQ0sJA186BSiwxwMYty0wgWgC6lsY4QQzuNR/aAsr8DxLR7vsTxaPB3m5qAzO8i7D/Xu22OX52CxxDeNizXwg1+0iyKU6S5AOEKCkF52iJY8OucVOt2sq9q1aX2wBijG12ZWyuh6iVHMtJxrxEOTYpp1h481ixBvt809hte2J26mn0hbWPW8v14X/LsS+5Mf5/0CcHm72tZ+EELyeDGI4TeZQeTw3Yf97KZfQ83cO15Ggzg=="
}
```
```

--------------------------------

### Initiate Payment

Source: https://alchemypay.readme.io/docs/create-order-2

This endpoint allows merchants to initiate a payment transaction by providing necessary details such as currency, amount, and callback URLs. It returns a payment URL for the user to complete the transaction.

```APIDOC
## POST /api/v1/buy/submit_order

### Description
Initiates a cryptocurrency purchase transaction. The user will be redirected to a payment page to complete the purchase.

### Method
POST

### Endpoint
/api/v1/buy/submit_order

### Parameters
#### Query Parameters
None

#### Request Body
- **side** (string) - Required - Specifies the transaction side, typically 'BUY'.
- **cryptoCurrency** (string) - Required - The cryptocurrency to be purchased (e.g., 'USDT').
- **address** (string) - Required - The user's wallet address for receiving the cryptocurrency.
- **network** (string) - Required - The blockchain network for the transaction (e.g., 'BSC').
- **fiatCurrency** (string) - Required - The fiat currency for the transaction (e.g., 'AUD').
- **amount** (number) - Required - The amount of fiat currency to be used for the purchase.
- **merchantOrderNo** (string) - Required - Unique identifier for the order from the merchant's system.
- **depositType** (number) - Required - Type of deposit, specific value depends on implementation (e.g., 2).
- **payWayCode** (string) - Required - Code representing the payment method (e.g., '501').
- **redirectUrl** (string) - Required - URL to redirect the user after a successful or failed payment attempt.
- **callbackUrl** (string) - Required - URL to receive asynchronous notifications about the order status.

### Request Example
```json
{
    "side": "BUY",
    "cryptoCurrency": "USDT",
    "address": "0x3E544857595654Ab***********",
    "network": "BSC",
    "fiatCurrency": "AUD",
    "amount": 50,
    "merchantOrderNo": "20259221************",
    "depositType": 2,
    "payWayCode": "501",
    "redirectUrl": "https://ramp.***pay.io/order?merchantOrderNo=20259221***********&redirectUrl=https%3A%2F%2Fwww.ABC.net",
    "callbackUrl": "https://api.ramp.***pay.io/order/callback/alchemypay?merchantOrderNo=202592215**********"
}
```

### Response
#### Success Response (200)
- **success** (boolean) - Indicates if the request was successful.
- **returnCode** (string) - Response status code. See [Return Code List](https://alchemypay.readme.io/v4.0.2/docs/response-code-list).
- **returnMsg** (string) - Description of the response status code.
- **extend** (string) - Reserved field.
- **data** (object) - Contains order details.
  - **orderNo** (string) - The unique order number generated by AlchemyPay.
  - **payUrl** (string) - The URL where the user can proceed to the payment page.
- **traceId** (string) - Unique identifier for request tracing and debugging.

#### Response Example (Success)
```json
{
    "success": true,
    "returnCode": "0000",
    "returnMsg": "SUCCESS",
    "extend": "",
    "data": {
        "orderNo": "1430459042606*******",
        "payUrl": "https://ramp.alchemypay.org/#/paymentMethod?token=ACH2906612342%40ACH%40ee6Y3HTKu8O***********************&email=OaViuSG0Be%2BpIiW8%2B%2F49Vr5f9EcgrP7NXDEfVpSVaDc%3D&orderNo=143045904260*******&id=ee6Y3HTKu8O********L8A%3D%3D&cardFlag=false"
    },
    "traceId": "68f888cc0ebd6a3754c3494b90eefce3"
}
```

#### Error Response Example
```json
{
    "success": false,
    "returnCode": "3103",
    "returnMsg": "Please refresh timestamp",
    "extend": "",
    "data": null,
    "traceId": "64ed9681618806b022dd303e2ea1ed13"
}
```
```

--------------------------------

### Example of Decryption

Source: https://alchemypay.readme.io/docs/api-integration-4

Provides a Python function example for decrypting the RSA encrypted and Base64 encoded data received from the API.

```APIDOC
## Example of Decryption

```python
def decrypt(encrypted_data: str, private_key: str) -> str:
    private_key_bytes = private_key.encode('utf-8')
    encrypted_data = base64.b64decode(encrypted_data)

    # Deserialize the private key from PEM format
    private_key_obj = serialization.load_pem_private_key(private_key_bytes, password=None, backend=default_backend())

    # Determine the appropriate chunk size based on the private key size
    key_size_bytes = private_key_obj.key_size // 8  # Convert bits to bytes
    decrypted_data = b""

    # Decrypt the data in chunks based on the key size
    for offset in range(0, len(encrypted_data), key_size_bytes):
        chunk = encrypted_data[offset:offset + key_size_bytes]
        decrypted_chunk = private_key_obj.decrypt(chunk, padding.PKCS1v15())
        decrypted_data += decrypted_chunk

    return decrypted_data.decode('utf-8')
```
```

--------------------------------

### Generate AlchemyPay On-Ramp URL and Signature (Python)

Source: https://alchemypay.readme.io/docs/ramp-signature-description

This snippet demonstrates how to generate the necessary signature and construct the final URL for AlchemyPay's on-ramp service. It includes setting up request parameters, generating a string to sign, creating the signature using a secret key and timestamp, and finally constructing the complete URL for the on-ramp transaction. Ensure you replace placeholder values with your actual `appId`, `secretKey`, and other relevant parameters.

```python
on_ramp_http_method = "GET"
on_ramp_request_path = "/index/rampPageBuy"
timestamp = str(int(time.time() * 1000))  # Current timestamp in milliseconds

app_id = "***" # relpace with your appId
on_ramp_secret_key = "***" # relpace with your secretKey

# Request parameters
params_to_sign = {
    'crypto': 'USDT',
    'fiatAmount': '15',
    'fiat': 'USD',
    'merchantOrderNo': '1631231234567890123455',# Needs to be unique
    'network': 'BSC',
    'callbackUrl': 'https://google.com',
    'redirectUrl': 'https://google.com',
    'timestamp': timestamp,
    'appId': app_id,
}

# Generate raw data to sign
raw_data_to_sign = get_string_to_sign(params_to_sign)
on_ramp_request_path_with_params = f"{on_ramp_request_path}?{raw_data_to_sign}"
on_ramp_signature = generate_signature(timestamp, on_ramp_http_method, on_ramp_request_path_with_params, on_ramp_secret_key)

raw_data_to_sign = get_string_to_sign(params_to_sign)

# Generate final URL
final_url = f"https://ramptest.alchemypay.org?{raw_data_to_sign}&sign={on_ramp_signature}"

print(f"On Ramp Signature: {on_ramp_signature}")
print(f"final url: {final_url}")
```

--------------------------------

### JSON Response Parameters Example

Source: https://alchemypay.readme.io/docs/off-ramp-hiding-receiving-address-page

Example JSON structure for AlchemyPay API responses. This includes fields for success status, return codes, messages, and extended data.

```json
{
    "success": true,
    "returnCode": "string",
    "returnMsg": "string",
    "extend": "string",
    "data": {}
}
```