# Introduction

Turn your crypto into dollars fast for spending with the MuseCard.

Welcome to the documentation for the MuseWallet Card API! This API provides partners with a flexible and efficient way to manage their card accounts, top-up and transfers processes.

The Card API supports a range of resources and endpoints, including the ability to create and manage card users, process transactions and transfers, and manage your entire card issuing program.

This documentation provides an overview of the Card API's resources and endpoints, as well as detailed information on each of the available modes of operation. It is designed to help partners get up and running with the API quickly and efficiently.

## Getting Started

Access to Card API is authenticated using an API access key combined with cryptographically signed API requests.

{% content-ref url="/pages/U5TCN1aUaXusm2oOgSEe" %}
[Getting Started](/getting-started)
{% endcontent-ref %}

Additionally, you can view the API documentation:

{% content-ref url="/pages/vBnPHQ7nthmPKOSpI1KH" %}
[API Reference](/reference/api-reference)
{% endcontent-ref %}


# Getting Started

The Card API is organized around [REST](http://en.wikipedia.org/wiki/Representational_State_Transfer). Our API has predictable resource-oriented URLs, accepts [JSON-encoded](http://www.json.org/) request bodies, returns [JSON-encoded](http://www.json.org/) responses, and uses standard HTTP response codes, authentication, and verbs.

\
All API uses API secret keys to authenticate requests. Any request that doesn't include an API key will return an error.

## Issuing API Credentials

Generate an API secret key for signing requests (see the next section for how to sign requests with the API secret key)::

\* Signature argorithm:

```
SHA1WithRSA
```

\
**First,** Run the following command line to generate an RSA 2048 private key (stored in muse\_secret.key):

<pre><code><strong>//generate new private key
</strong><strong>openssl req -new -newkey rsa:2048 -nodes -keyout muse_secret.key
</strong>
//export public key from private key
openssl rsa -in muse_secret.key -pubout
</code></pre>

{% hint style="info" %}
Make sure you keep the API secret key safe and secure!
{% endhint %}

**Then go to the** [**dashboard**](https://agent.musepay.io) **and upload the public key.** MuseCard will use your public key to verify the API calls.

<figure><img src="/files/lwF916gHlDEL4WxttVUq" alt=""><figcaption></figcaption></figure>

**Also remember to download MuseCard's public key** as you need to verify the notification from MuseCard API.

## Signing a Request

All API calls must be authenticated.

{% hint style="info" %}

* all the fields should be sorted in *alphabetical order* by the *key*
* *Empty* field should be exclude from the signature.
* fields key name are case sensitive
  {% endhint %}

For example：

assume the raw data are below：

```
partner_id:200001
request_id:2022031620000900005143515921
nonce:5K8264ILTKCH16CQ2502SI8ZNMTM67VS  
```

step 1: the data should be put in the format of 'key=value' ,and sorted in *alphabetical order* by the *key.*

{% code overflow="wrap" %}

```
message="nonce=5K8264ILTKCH16CQ2502SI8ZNMTM67VS&partner_id=100001&request_id=2020031620000900005143515921"
```

{% endcode %}

step 2: attach the api signature

{% code overflow="wrap" %}

```
sign=Base64Utils.encodeToString(sign(message,privateKey))
```

{% endcode %}

<details>

<summary>Code example（JAVA）</summary>

```java
// Some code
import org.springframework.util.Base64Utils;
import java.security.KeyFactory;
import java.security.PrivateKey;
import java.security.Signature;
import java.security.spec.PKCS8EncodedKeySpec;

public static final String SIGN_ALGORITHMS = "SHA1WithRSA";

try {
    PKCS8EncodedKeySpec priPKCS8 = new PKCS8EncodedKeySpec(Base64Utils.decodeFromString(privateKey));
    KeyFactory keyf = KeyFactory.getInstance("RSA");
    PrivateKey priKey = keyf.generatePrivate(priPKCS8);
    Signature signature = Signature.getInstance(SIGN_ALGORITHMS);
    signature.initSign(priKey);
    signature.update(content.getBytes(inputCharset));
    byte[] signed = signature.sign();
    return Base64Utils.encodeToString(signed);
 } catch (Exception e) {
    e.printStackTrace();
 }
```

</details>

<details>

<summary>Code example（Javascript）</summary>

````java
```javascript
import { hex2b64, KJUR } from 'jsrsasign'
import queryString from 'query-string'
import Axios from 'axios'

function buildCommonParams() {
  return {
    partner_id: this.partnerId,
    sign_type: 'RSA',
    timestamp: new Date().getTime(),
    nonce: new Date().getTime()
  }
}

function buildSignContent(params) {
  // console.log(`privateKey: `, this.privateKey)
  Object.keys(params).forEach(key => {
    if (!params[key]) {
      params[key] = undefined
    }
  })
  params.sign = undefined
  return queryString.stringify(params, { encode: false })
}

function sign(content) {
  console.log(`sign content: `, content)
  const sig = new KJUR.crypto.Signature({ 'alg': 'SHA1withRSA', 'prov': 'cryptojs/jsrsa', 'prvkeypem': `-----BEGIN PRIVATE KEY-----${this.privateKey}-----END PRIVATE KEY-----` })
  // console.log(sig)
  sig.updateString(content)
  const signedHex = sig.sign()
  // console.log(signedHex)
  const result = hex2b64(signedHex)
  console.log(`result: `, result)
  return result
}

// example
const data = Object.assign(this.buildCommonParams(), {
  currency
})
const content = this.buildSignContent(data)
data.sign = this.sign(content)
return this.axios({
  url: '/v1/carduser/creaate',
  method: 'post',
  data: data
})
```
````

</details>

<details>

<summary>Code example（PHP）</summary>

````java
```php
<?php
// 原始数据
$data = "nonce=1694076760022&partner_id=2100063&sign_type=RSA&timestamp=1694076760022&user_id=1100133&user_xid=2";

// 私钥（从文件或字符串中获取）
//$privateKeyPem = file_get_contents("../muse_secret.key");
$privateKeyPem = "-----BEGIN PRIVATE KEY-----
MIIEvAIBADANBgkqhkiG9w0BAQEFAASCBKYwggSiAgEAAoIBAQCnI1kB3OyurSfUaqIc7QPVbehYFeAXz3wRbr0KfL3bkF42r9lKUV5s5S3Bqfwu/L2r8kCFCVg9p6BBEZQFoGNp0LHqYThm89rWfzfFom6hncnUIUu67PYxq2tjazZRj/PxKjaGckPowXe6tbLapV2SiexdXFbW9SlsQQstXQW75aug+PElCYmy4dnv2f7OTF1PAkUTxTR1WNVhWZMRdqozmko3UsWDmT92JSYIzeES2AjktWYNAFrKGv7k/66jVHbieS9JAN6XU5EzBQ1pvlBk3oLHYRk0YKJG9Xrw822OLN8hO/Ty0et7qy/f9C38Nfw4UG4b+ZySZQJ8WbKLJMAbAgMBAAECggEAHRvk5pQpjIqPw0kHDu6gmk1YB+9XZg4213pn5imvj0vnfLLHr0/YmDKZ8369cxmFlyrL3d+wxJwrJun+07QJXGaCdgWUoymZVX42om8VwYQPoKhj3hxjDGeEfn4vqajenYPylxvTg/gd+CCpE7d1Qo5O4juwzCNKoZX6cl4fH4gqUk/yxxzFtUdA3knECmC0SxxesSqKwlKhFPfkLdvH2lBuhojfE+2Yo9AMFz4GfvDA4ds7SYPplm7K/57EA0qE75IBxuCnUIBimMFViZanmh08zbHVdlUcN1fXlxJnyv5dXh65OzLU7t96S1OXsmT3dMpRY4iJkAHdLgKLcRzSQQKBgQDdXtDqgSLV9fv5W9RABfCKlabdO+jzGwglWDQyBtTTioaTMEwY4UIxRm4YR4pXg0QNJnO6ROTcGYKrOJDD+L2WilVgVE4zntsN0Aj3vWLb7Sf/0u87nbU/HydPiSEz8H1AET60oWSXM1MLVaswynBz27QklmTINtskoF6gu3dx8QKBgQDBSLMPDLKawFSU3psRRZVQpHBQQjvkeqBHFDQzeOReQvnExuTQ3F7CE7Vw57+pvyS905sirmwUGfS+1ACqeXVz4Kn9rV2GS930oCBplJQgs7aJK0p0fALvrtL+Qjsga3FDAS8xHPzTDj66NelJI1AOFiUY/VoKwdNn40D4KR3GywKBgCvrBbOgjxK3zJe6Gi/hfclgy0wU+LBSaplOGHzcUhjt4KkO6en9tq4j9O+oMdAO4M9jE46e4HCyNvRVMpNOo/5bz3hfAWzIVVk2LrFHx3cuY8MjTAcd0LmHKrtiz02IprCxOymG43gD3LPg+Sei4hB6RBEGLVRzXaK0llF5H8dhAoGAebfFgym04/1Qhnt03bibIjCbxf8f5m9OtdREV1G/RpkY31F9UQYl6kQtE8/thAEqKxyx6nI6/6Gk3fN2A+T/ER0fD/B4IBVwzhd0sehuK/Xgcps/hQF/e971YkblIzJmHhMF3ADsOiETYYKHyZYiWOybKhSJ+pI7BoY3KNADv2cCgYAWS/XUef5V+R0xnGv6PvPWjT7q/Oa1G1RJ3uSVa3qL2WEWiwJpg+dC6wBTDsx7CRp5X0kodabLUSqCXkaho61AMwgiAgPCwGTXe4dZRs99cgNJjrer9Gcf/CYVA/43tMyuFFSvV794/oZ59nBaF3JyzeZxo3NKUgGpaKIKrlixkg==
-----END PRIVATE KEY-----";

$privateKey = openssl_pkey_get_private($privateKeyPem);

 echo "privateKeyPem: " . $privateKeyPem;
 echo "\n";

// 计算签名
$signature = "";
if (openssl_sign($data, $signature, $privateKey, OPENSSL_ALGO_SHA1)) {
    // 转换为Base64
    $base64Signature = base64_encode($signature);
    echo "Base64 Signature: " . $base64Signature;
} else {
    echo "Signing failed!";
}

// 释放私钥资源
// openssl_free_key($privateKey);
?>

```
````

</details>

step 3: finally get the request data

{% code overflow="wrap" %}

```
{     
"partner_id":"200001"     
"request_id":"2020031620000900005143515921"
"nonce":"5K8264ILTKCH16CQ2502SI8ZNMTM67VS"  
       
"sign":"LP0WrOk2N++KfizhZOoU23giqqylH1YX7U0NGm+U86Cznvf/IwvNrUVV1FZFrBOvAXBOi0EhUv2zxHzUwutww4Iuu25+qLV1L4I+kjwkE+70B0uFfoowSpCnuvHJ8fzT3uy4+KwPQCfT+H/BYEoXlSTO6VnAUD3qs9l/aQLKZxT7iURgdxVnc+7K5JiaThZ+TqFTL3kaVDD12H2orznA/QAhiosqIZXvpj4BbsvZO/c92dwS18HJKB5+qFxOwU+bsgFz6La+7ZZEnfS9cgIB43qeNi7eIVHwOH+YddbN8t+QxNDCZAaAf6p9mX8OhsuBi93cJZwh52jqmoFluOJbww=="
}

```

{% endcode %}

## IP Whitelisting

\
MuseCard supports restriction of API calls to be accepted only from a specific IP address per API key. If you wish to whitelist your IP address, please contact our technical support with the IP of the machine running your API client and the matching API key.

<br>


# Supported Assets

List All the supported crypto assets by MuseCard.

<table><thead><tr><th width="154">Currency</th><th>Chain</th><th data-hidden>Chain</th><th data-hidden>Decimals</th><th data-hidden>Address format</th><th data-hidden>Deposit Threshold</th></tr></thead><tbody><tr><td>USDT_TRC20</td><td>TRX</td><td>TRX</td><td>6</td><td>Typically 34 characters long with the capital letter "T"</td><td>5</td></tr><tr><td>USDT_ERC20</td><td>Ethereum</td><td>Ethereum</td><td>6</td><td>42-character string, beginning with '0x'</td><td>5</td></tr><tr><td>USDT_ARB</td><td>Arbitrum</td><td></td><td></td><td></td><td></td></tr><tr><td>USDT_BSC</td><td>BNB Smart Chain</td><td></td><td></td><td></td><td></td></tr><tr><td>USDC_ERC20</td><td>Ethereum</td><td></td><td></td><td></td><td></td></tr><tr><td>USDC_ARB</td><td>Arbitrum</td><td></td><td></td><td></td><td></td></tr></tbody></table>


# How to Issue a Card

<figure><img src="/files/278G5ujbSvtWaGtUHaYR" alt=""><figcaption></figcaption></figure>

### 1. Get Card Product ID

When issuing a card, the productId must be specified and determines the card product to issue. The card product determines the card type, card face, card features, benefits, interest rates, capabilties, etc. The list of available productIds is static will be provided by your solution manager. Also you can retrieve the productIds from the agent's portal (<https://agent.musepay.io/>).

### 2. Create Card Holder

Go to Page [Getting Started](/getting-started) and set up your API access key. and then perform API requests to create user as card holder in accordance to the specification provided in [User](/reference/api-reference/card-api/card-user) endpoints.

### 3. Apply a Card

Once a card holder is created, you can continue to create card application in accordance to the specification provided in [Card](/reference/api-reference/card-api/card#apply-card) endpoints.

### 4. Top Up

* Firstly, you need to recharge a certain amount of crypto assets to your agent account. Go to the agent's portal and navigate to Balance -> Deposit Coin as follow, where you can obtain a crypto address. After the cryptocurrency is confirmed on chain, your agent account will have a balance.

<figure><img src="/files/u6bbrKfihwdLOGh7VmFq" alt=""><figcaption></figcaption></figure>

* Then, you can Top up in accordance to the specification provided in [Top Up](/reference/api-reference/card-api/card-account#top-up-card) endpoints. the system will transfer the specified amount from your agent account to your designated card according to your api request.

  <br>


# Card Transactions Verification

This document describes the workflow for verifying card transactions via webhook integration. It outlines how partners can receive transaction verification messages and interact with clients to complete the verification process.

<figure><img src="/files/DM1CfiJOHrSniifkmYcX" alt=""><figcaption></figcaption></figure>

### Workflow Overview

#### Step 1: Verification Trigger

* When a transaction requires verification (such as 3DS or OTP), VISA triggers the process.
* MuseCard receives the verification event from VISA.

#### Step 2: Webhook Notification to Partner System

MuseCard sends a webhook notification to the Partner System:

* CARD\_TX\_OOB: Out-of-band verification (client confirmation required).
* CARD\_TX\_OTP: One-time password (OTP) verification.
* CARD\_TX\_3DS\_URL: 3D Secure verification URL.

#### Step 3: Client Interaction

The Partner System forwards the verification message to the client:

* For CARD\_TX\_OTP, the client inputs the OTP code.
* For CARD\_TX\_3DS\_URL, the client clicks the verification URL to complete the 3D Secure process.
* For CARD\_TX\_OOB, the Partner System pushes a message to the client for manual confirmation.

### 2. CARD\_TX\_OOB Model (Out-of-Band Verification)

1. The client receives the verification request via the Partner System.
2. The client confirms or declines the transaction.
3. The Partner System sends the result to MuseCard via API:
   * POST [/txn-verification-confirm](/reference/api-reference/card-api/card#confirm-transaction) — to confirm the transaction.
   * POST [/txn-verification-decline](/reference/api-reference/card-api/card#reject-transaction) — to decline the transaction.
4. MuseCard processes the response and sends the result to VISA via callback.

***

### 3. Key Notes

* All webhook events are sent to the Partner System in real time.
* The Partner System is responsible for delivering the message to the client.
* Timely processing of verification responses is crucial to avoid transaction delays.


# API Reference

## Enviroment

The base URL for Production enviroment is: `https://api.musepay.io`

The base URL for Test enviroment is: `https://api.test.musepay.io`

## Demo Client

#### Java

{% embed url="<https://github.com/jsirReal/musevcc-demo>" %}

## Request Common Parameters

Every request must contain the following parameters in the body:

{% content-ref url="/pages/asvitkRsyFdj4hYKqXf9" %}
[Common Parameters](/reference/api-reference/common-parameters)
{% endcontent-ref %}

## Card API

{% content-ref url="/pages/f52gC26bMHMRWuDtKUaM" %}
[Card API](/reference/api-reference/card-api)
{% endcontent-ref %}


# Common Parameters

**Every request must contain the following parameters in the body:**

<table><thead><tr><th width="154">Parameters</th><th width="104">Type</th><th>Desc</th></tr></thead><tbody><tr><td><em>partner_id</em></td><td>String</td><td>The ID of your Account allocated from MusePay.</td></tr><tr><td><em>sign_type</em></td><td>String</td><td>fixed value: "RSA".</td></tr><tr><td><em>timestamp</em></td><td>String</td><td>The time at which the request was called, in seconds since Epoch.</td></tr><tr><td><em>nonce</em></td><td>String</td><td>Unique random number or string. Each API request needs to have a different nonce.</td></tr><tr><td><em>sign</em></td><td>String</td><td>Base64 encoded signature string.</td></tr></tbody></table>


# Shared Quota

API endpoints pertaining to the shared-quota.

{% hint style="warning" %}
Every request must contain [common parameters](/reference/api-reference/common-parameters)
{% endhint %}

{% hint style="info" %}
Demo code can be found at [Github](/reference/api-reference#demo-client)
{% endhint %}

### **Shared Quota**

Multiple Shared Quota Cards can be issued under a single Budget Quota, allowing all cards to share the same budget balance.

Shared Quota Cards only define individual spending limits for each card; they do not carry actual funds themselves. All fees, transactions, and refunds are directly settled against the Budget Quota balance.

Funds transfer into or out from the Budget Quota are directly linked to the Main Account balance.

> **Note:**\
> If the total spending limits assigned to all Shared Quota Cards exceed the available Budget Quota balance, an over-limit fee may apply based on the excess amount.

### **Over-limit Fee Explanation**

Each Budget Quota represents the actual funds deposited by the merchant. However, you may assign card limits exceeding the total Budget Quota.

If the total card limits exceed the actual Budget Quota balance, the excess amount will be considered as an over-limit allocation and **will incur a management fee on the exceeding portion.**

**Fee Calculation Example:**

**Example 1:**

Merchant funds 50,000 USDT into the Budget Quota and there are 10 cards under this budget quota.

They assign limits of 10,000 USDT to each of 10 cards (total assigned limits = 100,000 USDT).

Over-limit amount = 100,000 USDT - 50,000 USDT = 50,000 USDT.

Management fee will apply to the 50,000 USDT over-limit amount and will be charged in daily basis.

**Example 2:**

Merchant funds 30,000 USDT into the Budget Quota.

Limits assigned to 5 cards:

* Card 1: 10,000 USDT
* Card 2: 10,000 USDT
* Card 3: 10,000 USDT
* Card 4 & Card 5: 0 USDT

  Total assigned limits = 30,000 USDT → No over-limit fee (limits match the budget).

### Integration Flow

> Create Budget Quota → Fund Budget Quota → Apply for Shared Quota Cards

[**Step 1: Create a Budget Quota**](#create-a-budget-quota)

Initiate the creation of a Budget Quota. This serves as the shared fund pool that will be used by all linked Shared Quota Cards.

[**Step 2: Fund the Budget Quota**](#fund-the-budget-quota)

Deposit funds into the Budget Quota. The deposited amount will become the available balance for all associated Shared Quota Cards.

[**Step 3: Apply for Shared Quota Cards**](#apply-for-shared-quota-cards)

Once the Budget Quota is funded, you can issue Shared Quota Cards under this quota.

Each card’s spending limit can be adjusted through the [Top-up API](/reference/api-reference/card-api/card-account#top-up-card). This top-up action does not deduct from the Budget Quota balance; it only defines the card’s spending limit.

## Create a b**udget** quota

<mark style="color:green;">`POST`</mark> `https://api.musepay.io/v1/card/share-quota/quota/create`

#### Request Body

| Name                                                 | Type   | Description                                 |
| ---------------------------------------------------- | ------ | ------------------------------------------- |
| request\_id<mark style="color:red;">\*</mark>        | String | External identifier for the create request. |
| card\_product\_id<mark style="color:red;">\*</mark>  | String | Product ID of the card to be related        |
| card\_level<mark style="color:red;">\*</mark>        | String | the card level of the card product          |
| share\_quota\_name<mark style="color:red;">\*</mark> | String | the name of the budget quota                |
| remark                                               | String | remark                                      |

{% tabs %}
{% tab title="200: OK Success" %}

```json
{
    // Response
   "code":200,
   "message":"success",
   "data": {
        "share_quota_id": "2469990273197955",
        "share_quota_status": "NORMAL"
    }
}
```

{% endtab %}
{% endtabs %}

## **Fund the Budget Quota**

<mark style="color:green;">`POST`</mark> `https://api.musepay.io/v1/card/share-quota/quota/tx/adjustment`

#### Request Body

| Name                                               | Type    | Description                          |
| -------------------------------------------------- | ------- | ------------------------------------ |
| share\_quota\_id<mark style="color:red;">\*</mark> | String  | the budget quota id                  |
| request\_id<mark style="color:red;">\*</mark>      | String  | External identifier for the request. |
| amount<mark style="color:red;">\*</mark>           | Integer | the amount to set                    |
| remark                                             | String  | remark                               |

{% tabs %}
{% tab title="200: OK Success" %}

```json
{
    // Response
   "code":200,
   "message":"success",
   "data": {
        "status": "APPLYING",
        "order_no": "2469990273197955",
        "amount": "120",
        "request_id": "afdsfasf234324"
    }
}
```

{% endtab %}
{% endtabs %}

## **Apply for Shared Quota Cards**

<mark style="color:green;">`POST`</mark> `https://api.musepay.io/v1/card/share-quota/apply`

#### Request Body

| Name                                                | Type   | Description                                                                                                               |
| --------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------- |
| user\_id<mark style="color:red;">\*</mark>          | String | The user id is an account that holds the funds, balances, and transactions that are used to make purchases with the card. |
| request\_id<mark style="color:red;">\*</mark>       | String | External identifier for the issuing request.                                                                              |
| card\_product\_id<mark style="color:red;">\*</mark> | String | Product ID of the card to be issued                                                                                       |
| card\_level<mark style="color:red;">\*</mark>       | String | the card level of the card product to apply                                                                               |
| phone\_number<mark style="color:red;">\*</mark>     | String | <p>Mobile phone number of card holder.<br><strong>This phone number should be pre-verified by the partner.</strong></p>   |
| phone\_area\_code<mark style="color:red;">\*</mark> | String | Country *calling* codes                                                                                                   |
| embossed\_name                                      | String | the embossed name in card face                                                                                            |
| share\_quota\_id<mark style="color:red;">\*</mark>  | String | the budget quota id                                                                                                       |

{% tabs %}
{% tab title="200: OK Success" %}

```json
{
    // Response
   "code":200,
   "message":"success",
   "data": {
        "apply_status": "APPLYING",
        "apply_id": "2469990273197955",
        "request_id": "afdsfasf234324"
    }
}
```

{% endtab %}
{% endtabs %}

## Query b**udget** quota records

<mark style="color:green;">`POST`</mark> `https://api.musepay.io/v1/card/share-quota/quota/list`

#### Request Body

| Name             | Type   | Description                               |
| ---------------- | ------ | ----------------------------------------- |
| share\_quota\_id | String | the budget quota id (optional)            |
| limit            | String | page size, default 10, between 1 and 1000 |
| page             | int    | page number, default 1                    |

{% tabs %}
{% tab title="200: OK Success" %}

```json
{
  "code": "200",
  "data": {
    "total": 100,
    "data": [
      {
        "share_quota_id": "TD13614342296065",
        "share_quota_name": "aaaaa",
        "card_product_id": "2daca29b5ed4e28a92dca87",
        "card_level": 1,
        "share_quota_status": "xx",
        "share_quota_currency": "USDT",
        "available_quota_balance":12321,
        "outgoing_quota_balance": 1696861482753,
        "total_usage_quota_balance": 1696861482753,
        "available_card_tx_quota": 1696861482753,
        "total_card_tx_quota": 1696861482753,
        "total_issue_card_count": 10
      },
    ]
  },
  "message": "success"
}
```

{% endtab %}
{% endtabs %}

## Query Budget Quota Adjustment History

<mark style="color:green;">`POST`</mark> `https://api.musepay.io/v1/card/share-quota/quota/tx/list`

#### Request Body

| Name             | Type   | Description                                                       |
| ---------------- | ------ | ----------------------------------------------------------------- |
| share\_quota\_id | String | the budget quota id (optional)                                    |
| request\_id      | String | External identifier for the adjust request.                       |
| start\_time      | Long   | Start time in milliseconds (Unix timestamp), e.g., 1748188799000L |
| end\_time        | Long   | End time in milliseconds (Unix timestamp), e.g., 1748188799000L   |
| limit            | String | page size, default 10, between 1 and 1000                         |
| page             | int    | page number, default 1                                            |

{% tabs %}
{% tab title="200: OK Success" %}

```json
{
  "code": "200",
  "data": {
    "total": 100,
    "data": [
      {
        "share_quota_id": "TD13614342296065",
        "order_no": "aaaaa",
        "status": "dsf",
        "request_id": "2daca29b5ed4e28a92dca87",
        "amount":12321,
        "transaction_time": 1748188799000
      },
    ]
  },
  "message": "success"
}
```

{% endtab %}
{% endtabs %}


# Fund API


# Partner

Query the balance and deposit address of the partner.

{% hint style="warning" %}
Every request must contain [common parameters](/reference/api-reference/common-parameters)
{% endhint %}

{% hint style="info" %}
Demo code can be found at [Github](/reference/api-reference#demo-client)
{% endhint %}

## Partner Balance

<mark style="color:green;">`POST`</mark> `/v1/balance/partner`

Query the balance of the partner

#### Request Body

| Name                                       | Type   | Description                            |
| ------------------------------------------ | ------ | -------------------------------------- |
| currency<mark style="color:red;">\*</mark> | String | which the balance needs to be queried. |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
  "code": "200",
  "data": {
    "currency": "USDT_TRC20",
    "balance": "100",
    "availableBalance": "100",,
    "freezeBalance": "0",
    "pendingSettleBalance": "0"
  },
  "message": "success"
}
```

{% endtab %}
{% endtabs %}

## Partner Main Address

<mark style="color:green;">`POST`</mark> `/v1/balance/partner-address`

Query the main deposit address of the partner

#### Request Body

| Name                                          | Type   | Description                            |
| --------------------------------------------- | ------ | -------------------------------------- |
| currency<mark style="color:red;">\*</mark>    | String | which the balance needs to be queried. |
| description<mark style="color:red;">\*</mark> | String | description                            |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
  "code": "200",
  "data": {
    "currency": "USDT_ERC20",
    "partner_id": "2001xx34",
    "address": "0x396795DdEFf2119820CddddsfderwfbB1860A",,
    "tag": "",
    "description": "111"
  },
  "message": "success"
}
```

{% endtab %}
{% endtabs %}


# Rate

{% hint style="warning" %}
Every request must contain [common parameters](/reference/api-reference/common-parameters)
{% endhint %}

{% hint style="info" %}
Demo code can be found at [Github](/reference/api-reference#demo-client)
{% endhint %}

## Trade Rate

<mark style="color:green;">`POST`</mark> `https://api.musepay.io/v1/rate/queryTradeRate`

Retrieves exchange rate between currencies.

#### Request Body

| Name                                            | Type   | Description                                                        |
| ----------------------------------------------- | ------ | ------------------------------------------------------------------ |
| baseCurrency<mark style="color:red;">\*</mark>  | String | the first currency appearing in a currency pair                    |
| quoteCurrency<mark style="color:red;">\*</mark> | String | used to determine the value of the base currency                   |
| symbolTradeType                                 | String | buy or sell base on baseCurrency,default sell,                     |
| orderType                                       | String | used for specific business types and can be left empty by default. |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
  "code": "200",
  "data": {
    "rate": "16078.8636472720095",
    "symbol": "USDT-IDR",
    "timeMills": 1678085017746,
    "expiredMills": 1678085077746
  },
  "message": "success"
}
```

{% endtab %}
{% endtabs %}


# Card API


# Card User

API endpoints pertaining to the cardholder.

{% hint style="warning" %}
Every request must contain [common parameters](/reference/api-reference/common-parameters)
{% endhint %}

{% hint style="info" %}
Demo code can be found at [Github](/reference/api-reference#demo-client)
{% endhint %}

## **Create User**

## Create a cardholder with identity information

<mark style="color:green;">`POST`</mark> `https://api.musepay.io/v1/carduser/create`

#### Request Body

| Name                                                         | Type   | Description                                                                                                                                                                                |
| ------------------------------------------------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| user\_xid<mark style="color:red;">\*</mark>                  | String | External identifier, unique under the partner.                                                                                                                                             |
| user\_name                                                   | String | Nickname of user account, this is a human-friendly non-unique name for a user account                                                                                                      |
| email<mark style="color:red;">\*</mark>                      | String | Email address of cardholder                                                                                                                                                                |
| individual<mark style="color:red;">\*</mark>                 | Object | Individual card holder identity information.                                                                                                                                               |
| individual.first\_name<mark style="color:red;">\*</mark>     | String | First name of cardholder                                                                                                                                                                   |
| individual.last\_name<mark style="color:red;">\*</mark>      | String | Last name / Surname of cardholder                                                                                                                                                          |
| individual.date\_of\_birth<mark style="color:red;">\*</mark> | String | Date of birth (YYYY-MM-DD)                                                                                                                                                                 |
| individual.occupation                                        | String | Occupation of card holder.                                                                                                                                                                 |
| individual.annual\_income                                    | String | Annual income of card holder in card currency                                                                                                                                              |
| document<mark style="color:red;">\*</mark>                   | Object | Government Issued Identification Document Information                                                                                                                                      |
| document.type<mark style="color:red;">\*</mark>              | String | 1 or 2, enums in [Document Type](/enums/document-type)                                                                                                                                     |
| document.number<mark style="color:red;">\*</mark>            | String | Identification document number.                                                                                                                                                            |
| document.country<mark style="color:red;">\*</mark>           | String | Issuing country of identification document in ISO3166-1 alpha-2 format                                                                                                                     |
| document.expiry\_date<mark style="color:red;">\*</mark>      | String | Expiry date of identification document (YYYY-MM-DD)                                                                                                                                        |
| document.front<mark style="color:red;">\*</mark>             | String | <p>The front of a document file encoded <strong>in data URI base64 encoded format.</strong></p><p>The following mime types are accepted for ID documents:<br>image/jpeg,<br>image/png.</p> |
| document.back                                                | String | <p>The back of a document file encoded in data URI base64 encoded format.</p><p>The back of a document file encoded in data URI base64 encoded format</p>                                  |
| document.face                                                | String | <p>The selfie photo file encoded <strong>in data URI base64 encoded format.</strong></p><p>The following mime types are accepted for ID documents:<br>image/jpeg,<br>image/png.</p>        |
| address                                                      | Object | Delivery address                                                                                                                                                                           |
| address.country                                              | String | Delivery country of identification document in ISO3166-1 alpha-2 format                                                                                                                    |
| address.city                                                 | String | Delivery city                                                                                                                                                                              |
| address.post\_code                                           | String | Delivery post code                                                                                                                                                                         |
| address.details                                              | String | Detail delivery address                                                                                                                                                                    |

{% tabs %}
{% tab title="200: OK Success" %}

<pre class="language-javascript"><code class="lang-javascript"><strong>{
</strong>"data":
   { 
    "user_xid":"aabcdfsf",  //user external id       
    "user_id":"8000123",    //user id
    "kyc_status":"0"
   },
"code":"200",
"message":"Success"
}
</code></pre>

{% endtab %}
{% endtabs %}

<details>

<summary>Code example</summary>

```java
// 
curl --location --request POST 'https://api.musepay.io/v1/carduser/create' \
--header 'Content-Type: application/json' \
--data-raw '{
    * "user_xid": "XUID9982674851738108",
      "user_name": "jasonwood", 
    * "email": "carduser001@musepay.io",     
    * "individual" : {
    *     "first_name": "Jack",
    *     "last_name": "Weather",
    *     "date_of_birth": "1988-02-02",
          "occupation": "01",
          "annual_income":"100000"
      },
      "document": {
    *     "type": "passport",
    *     "number": "G012345678",
    *     "country": "China",
    *     "expiry_date": "2030-10-10",
    *     "front": "afjkfjkasfjajsdfkasfjadsf",
    *     "back": "afjkfjkasfjajsdfkasfjasdafasf"
      },
      "address": {
          "country": "BR",
          "city": "RILA",
          "post_code": "GA1234",
          "details": "No.43 Rd Sky",

      }
}'
```

</details>

## **Create User with KYC link**

## Create a cardholder with KYC link

<mark style="color:green;">`POST`</mark> `https://api.musepay.io/v1/carduser/create-with-kyc-link`

#### Request Body

| Name                                        | Type   | Description                                                                           |
| ------------------------------------------- | ------ | ------------------------------------------------------------------------------------- |
| email<mark style="color:red;">\*</mark>     | String | Email address of cardholder                                                           |
| user\_xid<mark style="color:red;">\*</mark> | String | External identifier, unique under the partner.                                        |
| user\_name                                  | String | Nickname of user account, this is a human-friendly non-unique name for a user account |

{% tabs %}
{% tab title="200: OK Success" %}

```javascript
{
"data":
   { 
    "user_xid":"aabcdfsf",  //user external id       
    "user_id":"8000123",    //user id
    "kyc_status":"0",
    "link": "https://aaaa.com/kyc-page"
   },
"code":"200",
"message":"Success"
}
```

{% endtab %}
{% endtabs %}

## **Get User KYC link**

## Get a KYC link for user

<mark style="color:green;">`POST`</mark> `https://api.musepay.io/v1/carduser/kyc-link`

#### Request Body

| Name                                        | Type   | Description                                             |
| ------------------------------------------- | ------ | ------------------------------------------------------- |
| user\_xid<mark style="color:red;">\*</mark> | String | External identifier, unique under the partner.          |
| level\_name                                 | String | <p>LEVEL-1 or LEVEL-2.<br>Default value is LEVEL-1.</p> |

{% tabs %}
{% tab title="200: OK Success" %}

```javascript
{
"data":
   { 
    "user_xid":"aabcdfsf",  //user external id       
    "link": "https://aaaa.com/kyc-page"
   },
"code":"200",
"message":"Success"
}
```

{% endtab %}
{% endtabs %}

## **Get User**

## Get a collection of cardholders based on provided search criteria.

<mark style="color:green;">`POST`</mark> `https://api.musepay.io/v1/carduser/query`

#### Request Body

| Name                                        | Type   | Description |
| ------------------------------------------- | ------ | ----------- |
| user\_id                                    | String |             |
| phone\_number                               | String |             |
| email                                       | String |             |
| user\_xid<mark style="color:red;">\*</mark> | String |             |

{% tabs %}
{% tab title="200: OK Success" %}

```json
{
"data":
   { 
    "user_xid":"aabcdfsf",  //user external id       
    "user_id":"8000123",    //user id
    "kyc_status":"0",
    "email": "abc@abc.com",
    "phone_number": "2323",
    "last_name": "abc",
    "first_name": "abc",
    "document_type": "abc",
    "document_number": "aac234"
   },
"code":"200",
"message":"Success"
}
```

{% endtab %}
{% endtabs %}

## Upload User KYC

## Upload User KYC information

<mark style="color:green;">`POST`</mark> `https://api.musepay.io/v1/carduser/upload-kyc`

#### Request Body

| Name                                                         | Type   | Description                                                                                                                                                                                |
| ------------------------------------------------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| user\_xid<mark style="color:red;">\*</mark>                  | String | External identifier, unique under the partner.                                                                                                                                             |
| individual<mark style="color:red;">\*</mark>                 | Object | Individual card holder identity information.                                                                                                                                               |
| individual.first\_name<mark style="color:red;">\*</mark>     | String | First name of cardholder                                                                                                                                                                   |
| individual.last\_name<mark style="color:red;">\*</mark>      | String | Last name / Surname of cardholder                                                                                                                                                          |
| individual.date\_of\_birth<mark style="color:red;">\*</mark> | String | Date of birth (YYYY-MM-DD)                                                                                                                                                                 |
| individual.occupation                                        | String | Occupation of card holder.                                                                                                                                                                 |
| individual.annual\_income                                    | String | Annual income of card holder in card currency                                                                                                                                              |
| document<mark style="color:red;">\*</mark>                   | Object | Government Issued Identification Document Information                                                                                                                                      |
| document.type<mark style="color:red;">\*</mark>              | String | 1 or 2, enums in [Document Type](/enums/document-type)                                                                                                                                     |
| document.number<mark style="color:red;">\*</mark>            | String | Identification document number.                                                                                                                                                            |
| document.country<mark style="color:red;">\*</mark>           | String | Issuing country of identification document in ISO3166-1 alpha-2 format                                                                                                                     |
| document.expiry\_date<mark style="color:red;">\*</mark>      | String | Expiry date of identification document (YYYY-MM-DD)                                                                                                                                        |
| document.front<mark style="color:red;">\*</mark>             | String | <p>The front of a document file encoded <strong>in data URI base64 encoded format.</strong></p><p>The following mime types are accepted for ID documents:<br>image/jpeg,<br>image/png.</p> |
| document.back                                                | String | <p>The back of a document file encoded in data URI base64 encoded format.</p><p>The back of a document file encoded in data URI base64 encoded format</p>                                  |
| address                                                      | Object | Delivery address                                                                                                                                                                           |
| address.country                                              | String | Delivery country of identification document in ISO3166-1 alpha-2 format                                                                                                                    |
| address.city                                                 | String | Delivery city                                                                                                                                                                              |
| address.post\_code                                           | String | Delivery post code                                                                                                                                                                         |
| address.details                                              | String | Detail delivery address                                                                                                                                                                    |

{% tabs %}
{% tab title="200: OK Success" %}

<pre class="language-javascript"><code class="lang-javascript"><strong>{
</strong>"data":
   { 
    "user_xid":"aabcdfsf",  //user external id       
    "user_id":"8000123",    //user id
    "kyc_status":"0"
   },
"code":"200",
"message":"Success"
}
</code></pre>

{% endtab %}
{% endtabs %}

## Change user email

<mark style="color:green;">`POST`</mark> `https://api.musepay.io/v1/carduser/change-email`

When updating a user’s email, if the user has a card, the associated email on the card will be updated accordingly.

#### Request Body

| Name     | Type   | Description                     |
| -------- | ------ | ------------------------------- |
| user\_id | String | User unique ID                  |
| email    | String | New email address of cardholder |

**Response**

{% tabs %}
{% tab title="200" %}

```json
{
  "success": true
}
```

{% endtab %}
{% endtabs %}


# Card

create and query order information .

{% hint style="warning" %}
Every request must contain [common parameters](/reference/api-reference/common-parameters)
{% endhint %}

{% hint style="info" %}
Demo code can be found at [Github](/reference/api-reference#demo-client)
{% endhint %}

## Apply Card

## issue a card under a specific user.

<mark style="color:green;">`POST`</mark> `https://api.musepay.io/v1/card/apply`

Only one card can be issued under a single card product.

When issuing a card, the productId must be specified and determines the card product to issue. The card product determines the card type, card face, card features, benefits, interest rates, capabilities, etc.

#### Request Body

| Name                                                | Type   | Description                                                                                                               |
| --------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------- |
| user\_id<mark style="color:red;">\*</mark>          | String | The user id is an account that holds the funds, balances, and transactions that are used to make purchases with the card. |
| request\_id<mark style="color:red;">\*</mark>       | String | External identifier for the issuing request.                                                                              |
| card\_product\_id<mark style="color:red;">\*</mark> | String | Product ID of the card to be issued                                                                                       |
| card\_level<mark style="color:red;">\*</mark>       | String | the card level of the card product to apply                                                                               |
| phone\_number<mark style="color:red;">\*</mark>     | String | <p>Mobile phone number of card holder.<br><strong>This phone number should be pre-verified by the partner.</strong></p>   |
| phone\_area\_code<mark style="color:red;">\*</mark> | String | Country *calling* codes                                                                                                   |
| embossed\_name                                      | String | the embossed name in card face                                                                                            |

{% tabs %}
{% tab title="200: OK Success" %}

```json
{
    // Response
   "code":200,
   "message":"success",
   "data": {
        "apply_status": "APPLYING",
        "apply_id": "2469990273197955",
        "request_id": "afdsfasf234324"
    }
}
```

{% endtab %}
{% endtabs %}

## Query Apply Result

## query Card Apply Result

<mark style="color:green;">`POST`</mark> `https://api.musepay.io/v1/card/apply-result`

#### Request Body

| Name                                          | Type   | Description                                  |
| --------------------------------------------- | ------ | -------------------------------------------- |
| request\_id<mark style="color:red;">\*</mark> | String | External identifier for the issuing request. |
| apply\_id                                     | String | The apply ID of the card issuing             |
| user\_id<mark style="color:red;">\*</mark>    | String | The unique id in musewallet                  |

{% tabs %}
{% tab title="200: OK Success" %}

```javascript
{    
     "code":"200",
     "data":{
         "request_id":"2022093002029700786237858945",
         "user_id":"2000061",
         "apply_id":"abc123",
         "card_id":"xxxxx",
         "apply_status":"WAIT_AUDIT"
         },
   "message":"success"
}


```

{% endtab %}
{% endtabs %}

## Get Card

## get Card

<mark style="color:green;">`POST`</mark> `https://api.musepay.io/v1/card/query`

#### Request Body

| Name                                       | Type   | Description                    |
| ------------------------------------------ | ------ | ------------------------------ |
| card\_id<mark style="color:red;">\*</mark> | String | The card ID of the card issued |
| user\_id<mark style="color:red;">\*</mark> | String | The unique id in musewallet    |

{% tabs %}
{% tab title="200: OK Success" %}

```javascript
{    
     "code":"200",
     "data":{
         "user_id":"2000061",
         "card_id":"xxxxx",
         "phone_number":"1331236",
         "phone_area_code":"86",
         "product_id":"86",
         "card_level":1,
         "card_network":"masterCard",
         "card_type":"physical",
         "currency":"USD",
         "card_no_last4":"0086",
         "card_status":"PENDING_ACTIVE",
         "embossed_name":"coll boston",
         "expiry_month": "04",
         "expiry_year": "2030",
         "issue_time": "13788886666",
         "card_available_balance": 12321,
         "daily_purchaseLimit": 500000,
         "enable_present_transaction": false,
         "enable_noPresent_transaction": true
     }
   "message":"success"
}


```

{% endtab %}
{% endtabs %}

## Activate Card

## activate card

<mark style="color:green;">`POST`</mark> `https://api.musepay.io/v1/card/activate`

#### Request Body

| Name                                       | Type   | Description                    |
| ------------------------------------------ | ------ | ------------------------------ |
| card\_id<mark style="color:red;">\*</mark> | String | The card ID of the card issued |
| user\_id<mark style="color:red;">\*</mark> | String | The unique id in musewallet    |

{% tabs %}
{% tab title="200: OK Success" %}

```javascript
{    
     "code":"200",
     "data":{
         "user_id":"2000061",
         "card_id":"xxxxx",
         "card_status":"PENDING_ACTIVE"
     }
   "message":"success"
}


```

{% endtab %}
{% endtabs %}

## Update Phone

## update phone

<mark style="color:green;">`POST`</mark> `https://api.musepay.io/v1/card/update-phone`

#### Request Body

| Name                                                | Type   | Description                    |
| --------------------------------------------------- | ------ | ------------------------------ |
| card\_id<mark style="color:red;">\*</mark>          | String | The card ID of the card issued |
| user\_id<mark style="color:red;">\*</mark>          | String | The unique id in musewallet    |
| phone\_number<mark style="color:red;">\*</mark>     | String | New phone number for the card  |
| phone\_area\_code<mark style="color:red;">\*</mark> | String | countryCode                    |

{% tabs %}
{% tab title="200: OK Success" %}

```javascript
{    
     "code":"200",
     "data":{
         "user_id":"2000061",
         "card_id":"xxxxx",
         "status":""
     }
   "message":"success"
}


```

{% endtab %}
{% endtabs %}

##

## Lock Card

## lock card

<mark style="color:green;">`POST`</mark> `https://api.musepay.io/v1/card/lock`

#### Request Body

| Name                                       | Type   | Description                    |
| ------------------------------------------ | ------ | ------------------------------ |
| card\_id<mark style="color:red;">\*</mark> | String | The card ID of the card issued |
| user\_id<mark style="color:red;">\*</mark> | String | The unique id in musewallet    |

{% tabs %}
{% tab title="200: OK Success" %}

```javascript
{    
     "code":"200",
     "data":{
         "user_id":"2000061",
         "card_id":"xxxxx",
         "card_status":"LOCK"
     }
   "message":"success"
}


```

{% endtab %}
{% endtabs %}

## UnLock Card

## unlock card

<mark style="color:green;">`POST`</mark> `https://api.musepay.io/v1/card/unlock`

#### Request Body

| Name                                       | Type   | Description                    |
| ------------------------------------------ | ------ | ------------------------------ |
| card\_id<mark style="color:red;">\*</mark> | String | The card ID of the card issued |
| user\_id<mark style="color:red;">\*</mark> | String | The unique id in musewallet    |

{% tabs %}
{% tab title="200: OK Success" %}

```javascript
{    
     "code":"200",
     "data":{
         "user_id":"2000061",
         "card_id":"xxxxx",
         "card_status":"ACTIVE"
     }
   "message":"success"
}


```

{% endtab %}
{% endtabs %}

## Get Card Sensitive Info

## get Card sensitive info

<mark style="color:green;">`POST`</mark> `https://api.musepay.io/v1/card/card-sensitive-info`

Generate a short-lived one-time URL for retrieving sensitive information for a card. The returned URL must be consumed directly by the client facing application, through the client's IP address provided in the retrieval request.

The API Response of the callback URL will contain the following payload:

`{`

`"card_id": "akflf51b3",`

`"card_number": "4242424212341234",`

`"expiry_month": "11",`

`"expiry_year": "2028",`

`"security_code": "001"`

`}`

#### Request Body

| Name                                          | Type   | Description                    |
| --------------------------------------------- | ------ | ------------------------------ |
| card\_id<mark style="color:red;">\*</mark>    | String | The card ID of the card issued |
| ip\_address<mark style="color:red;">\*</mark> | String | Client IP address              |
| user\_id<mark style="color:red;">\*</mark>    | String | The unique id in musewallet    |

{% tabs %}
{% tab title="200: OK Success" %}

```javascript
{    
     "code":"200",
     "data":{
         "expiry":"2022-09-30", //YYYY-MM-DD
         "url":"https://abc.com/afd" //URL to retrieve card sensitive information
     }
   "message":"success"
}


```

{% endtab %}
{% endtabs %}

## Activate Physical Card

## activate physical card

<mark style="color:green;">`POST`</mark> `https://api.musepay.io/v1/card/activate-physical`

#### Request Body

| Name                                       | Type   | Description                    |
| ------------------------------------------ | ------ | ------------------------------ |
| card\_id<mark style="color:red;">\*</mark> | String | The card ID of the card issued |
| user\_id<mark style="color:red;">\*</mark> | String | The unique id in musewallet    |

{% tabs %}
{% tab title="200: OK Success" %}

```javascript
{    
     "code":"200",
     "data":{
         "user_id":"2000061",
         "card_id":"xxxxx",
         "card_status":"PENDING_ACTIVE"
     }
   "message":"success"
}


```

{% endtab %}
{% endtabs %}

## Change Card PIN

## get change PIN model

<mark style="color:green;">`POST`</mark> `https://api.musepay.io/v1/card/get-change-pin-model`

#### Request Body

| Name                                       | Type   | Description                    |
| ------------------------------------------ | ------ | ------------------------------ |
| card\_id<mark style="color:red;">\*</mark> | String | The card ID of the card issued |
| user\_id<mark style="color:red;">\*</mark> | String | The unique id in musewallet    |

{% tabs %}
{% tab title="200: OK Success" %}

```javascript
{    
     "code":"200",
     "message":"success",
     "cardPinChangeModel":"URL", // URL or API
     "url":"abc.com/change-pin"
}


```

{% endtab %}
{% endtabs %}

## change Card PIN

<mark style="color:green;">`POST`</mark> `https://api.musepay.io/v1/card/change-pin`

#### Request Body

| Name                                        | Type   | Description                                                                |
| ------------------------------------------- | ------ | -------------------------------------------------------------------------- |
| card\_id<mark style="color:red;">\*</mark>  | String | The card ID of the card issued                                             |
| card\_pin<mark style="color:red;">\*</mark> | String | New PIN, numeric pin, 6 digits only, must encrypted by platform public key |
| user\_id<mark style="color:red;">\*</mark>  | String | The unique id in musewallet                                                |

{% tabs %}
{% tab title="200: OK Success" %}

```javascript
{    
     "code":"200",
     "message":"success"
}


```

{% endtab %}
{% endtabs %}

<details>

<summary>Code Example for Pin Encryption</summary>

```java
// JAVA
// encrypt(pin, platformPublicKey)
    public static String encrypt(String text, String publicStr) throws Exception {
        PublicKey publicKey = getRSAPublicKey(publicStr);
        Cipher cipher = Cipher.getInstance("RSA");
        cipher.init(Cipher.ENCRYPT_MODE, publicKey);
        byte[] bytes = cipher.doFinal(text.getBytes());
        return Base64Utils.encodeToString(bytes);
    }
    
    @SneakyThrows
    private static RSAPublicKey getRSAPublicKey(String publicKey) {
        publicKey = trim(publicKey);

        KeyFactory kFactory = KeyFactory.getInstance("RSA");
        // decode base64 of your key
        byte[] yourKey =  Base64Utils.decodeFromString(publicKey);
        // generate the public key
        X509EncodedKeySpec spec =  new X509EncodedKeySpec(yourKey);
        return (RSAPublicKey) kFactory.generatePublic(spec);
    }

    private static String trim(String key) {
        return Arrays.stream(key.split("\n"))
                .filter(StringUtils::isNotBlank)
                .map(s -> s.replaceAll("\\s+", ""))
                .filter(i -> !i.startsWith("-----"))
                .collect(Collectors.joining());
    }
```

</details>

## Replace Card

## replace Card

<mark style="color:green;">`POST`</mark> `https://api.musepay.io/v1/card/replace`

replace with a new card under same card product

#### Request Body

<table><thead><tr><th width="239">Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>user_id<mark style="color:red;">*</mark></td><td>String</td><td>The unique id for card holder</td></tr><tr><td>original_card_id<mark style="color:red;">*</mark></td><td>String</td><td>The original card id</td></tr><tr><td>replace_reason<mark style="color:red;">*</mark></td><td>String</td><td>The replace reason</td></tr><tr><td>request_id<mark style="color:red;">*</mark></td><td>String</td><td>External identifier for the replace request.</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="200" %}

```json
{    
     "code":"200",
     "data":{
         "user_id":"6000061",
         "card_id":"xxxxx",
         "card_status":"PENDING_ACTIVE"
     }
   "message":"success"
}
```

{% endtab %}
{% endtabs %}

## Change Card Purchase Limit

## card limit

<mark style="color:green;">`POST`</mark> `https://api.musepay.io/v1/card/limitChange`

change card purchase limit

#### Request Body

<table><thead><tr><th width="239">Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>user_id<mark style="color:red;">*</mark></td><td>String</td><td>The unique id for card holder</td></tr><tr><td>card_id<mark style="color:red;">*</mark></td><td>String</td><td>The card id</td></tr><tr><td>daily_purchase_limit<mark style="color:red;">*</mark></td><td>Decimal</td><td>New daily purchase limit to set</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="200" %}

```json
{    
   "code":"200",
   "message":"success"
}
```

{% endtab %}
{% endtabs %}

## Reject Transaction

<mark style="color:green;">`POST`</mark> `https://api.musepay.io/v1/card/txn-verification-decline`

reject txn

#### Request Body

<table><thead><tr><th width="239">Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>user_id<mark style="color:red;">*</mark></td><td>String</td><td>The unique id for card holder</td></tr><tr><td>request_id<mark style="color:red;">*</mark></td><td>String</td><td>External identifier for the request.</td></tr><tr><td>card_id<mark style="color:red;">*</mark></td><td>String</td><td>The card id</td></tr><tr><td>token<mark style="color:red;">*</mark></td><td>String</td><td>OOB token to reject</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="200" %}

```json
{    
   "code":"200",
   "message":"success"
}
```

{% endtab %}
{% endtabs %}

## Confirm Transaction

<mark style="color:green;">`POST`</mark> `https://api.musepay.io/v1/card/txn-verification-confirm`

confirm txn

#### Request Body

<table><thead><tr><th width="239">Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>user_id<mark style="color:red;">*</mark></td><td>String</td><td>The unique id for card holder</td></tr><tr><td>request_id<mark style="color:red;">*</mark></td><td>String</td><td>External identifier for the request.</td></tr><tr><td>card_id<mark style="color:red;">*</mark></td><td>String</td><td>The card id</td></tr><tr><td>token<mark style="color:red;">*</mark></td><td>String</td><td>OOB token to confirm</td></tr></tbody></table>

**Response**

{% tabs %}
{% tab title="200" %}

```json
{    
   "code":"200",
   "message":"success"
}
```

{% endtab %}
{% endtabs %}


# Card Account

Retrieve information of card accounts

{% hint style="warning" %}
Every request must contain [common parameters](/reference/api-reference/common-parameters)
{% endhint %}

{% hint style="info" %}
Demo code can be found at [Github](/reference/api-reference#demo-client)
{% endhint %}

## Top Up Card

## top up card

<mark style="color:green;">`POST`</mark> `https://api.musepay.io/v1/cardaccount/topup`

#### Request Body

| Name                                          | Type   | Description                                 |
| --------------------------------------------- | ------ | ------------------------------------------- |
| request\_id<mark style="color:red;">\*</mark> | String | External identifier for the top up request. |
| card\_id<mark style="color:red;">\*</mark>    | String | The card ID of the card issued              |
| amount<mark style="color:red;">\*</mark>      | String | Amount to top up                            |
| currency<mark style="color:red;">\*</mark>    | String | Currency for amount deduction               |
| user\_id<mark style="color:red;">\*</mark>    | String | The unique user id in MuseWallet            |

{% tabs %}
{% tab title="200: OK Success" %}

```javascript
{
  "code": "200",
  "data": {
    "amount": "5.880000000000000000",
    "currency": "USDT_TRC20",
    "fee": "0",
    "order_no": "2023169681108404690947",
    "request_id": "e6dcba5ced67d59",
    "status": "PENDING"
  },
  "message": "success"
}


```

{% endtab %}
{% endtabs %}

## **Query Card Account Transactions**

## query card account transactions

<mark style="color:green;">`POST`</mark> `https://api.musepay.io/v1/cardaccount/transactions`

#### Request Body

| Name                                       | Type   | Description                                 |
| ------------------------------------------ | ------ | ------------------------------------------- |
| card\_id<mark style="color:red;">\*</mark> | String | The card ID of the card issued              |
| order\_no                                  | String | transaction order id                        |
| date\_range\_from                          | Number |                                             |
| date\_range\_to                            | Number |                                             |
| page\_size                                 | Number | default 50, between 1 and 1000              |
| user\_id<mark style="color:red;">\*</mark> | String | The unique user id in MuseWallet            |
| request\_id                                | String | External identifier for the top up request. |
| page\_number                               | Number | default 1                                   |
| tx\_status                                 | String | tx status                                   |
| tx\_type                                   | String | tx type                                     |
| detail\_id                                 | String |                                             |

{% tabs %}
{% tab title="200: OK Success" %}

```javascript

{
  "code": "200",
  "data": {
    "card_id": "VC130798262733",
    "page_number": 1,
    "page_size": 50,
    "total_count": 1,
    "transactions": [
      {
        "detailId": "TD13614342296065",
        "order": {
          "fee": 0,
          "feeCurrency": "USDT_TRC20",
          "orderAmount": 5.880000000000000000,
          "orderCurrency": "USDT",
          "orderNo": "202316968614802662142296064",
          "paymentAmount": 5.880000000000000000,
          "paymentCurrency": "USDT_TRC20",
          "rate": 1,
          "status": "SUCCESS"
        },
        "orderNo": "202316968614802302296064",
        "requestId": "2daca29b5ed4e28a92dca87",
        "txAmount": 5.880000000000000000,
        "txCreatedAt": 1696861480230,
        "txCurrency": "USDT",
        "txPostedAt": 1696861482753,
        "txStatus": "POSTED",
        "txType": "TOP_UP"
      },
      {
        "authorization": {
          "amount": 8862.81,
          "currency": "THB"
        },
        "detailId": "TD1362376942444550",
        "merchant": {
          "category": "Eating places and Restaurants",
          "country": "TH",
          "mcc": "5812",
          "name": "GINZADO (THAILAND)-SUK BANGKOK THA"
        },
        "txAmount": 250.220000000000000000,
        "txCreatedAt": 1696860705880,
        "txCurrency": "USDT",
        "txPostedAt": 0,
        "txStatus": "PENDING",
        "txType": "CHARGE"
      },
      {
        "detailId": "TD136452797095946",
        "order": {
          "fee": 0,
          "feeCurrency": "USDT_TRC20",
          "orderAmount": 5.880000000000000000,
          "orderCurrency": "USDT",
          "orderNo": "202316996491361410452797095945",
          "paymentAmount": 5.880000000000000000,
          "paymentCurrency": "USDT_TRC20",
          "rate": 1,
          "status": "SUCCESS"
        },
        "orderNo": "2023166596491361410452797095945",
        "requestId": "163490ae978202cf67945121f0",
        "txAmount": 5.880000000000000000,
        "txCreatedAt": 1696860659649,
        "txCurrency": "USDT",
        "txPostedAt": 1696860663335,
        "txStatus": "POSTED",
        "txType": "TOP_UP"
      }
    ],
    "user_id": 60004408
  },
  "message": "success"
}

```

{% endtab %}
{% endtabs %}


# Acquiring API


# Wallet Mode

{% hint style="warning" %}
Every request must contain [common parameters](/reference/api-reference/common-parameters)
{% endhint %}

## Deposit Address

### Retrieves a deposit address of a specific crypto asset for your end-users.

<mark style="color:green;">`POST`</mark> `/v1/order/deposit_address`

#### Request Body

| Name                | Type   | Description                                                                        |
| ------------------- | ------ | ---------------------------------------------------------------------------------- |
| currency\*          | String | the name of crypto asset to deposit                                                |
| customer\_ref\_id\* | String | The ID for the partner to associate the owner of funds(customer) with transactions |
| description         | String | extend info, don't store any sensitive information                                 |

200: OK

```json
{
    // Response
   "code":200,
   "message":"success",
   "data": {
        "currency": "ETH",
        "address": "0x55d398326f99059fF775485246999027B3197955",
        "tag": ""
    }
}
```

#### Code example

```
// 
curl --location --request POST 'https://api.musepay.io/v1/order/deposit_address' \ 
--header 'Content-Type: application/json' \ 
--data-raw '{ 
    * "partner_id": "2000001", 
    * "sign_type": "RSA", 
    * "timestamp": "1688371190810", 
    * "nonce": "abccefeafjkjsl", 
    * "sign": "examplesignnotcorrect", 
    * "currency": "USDT_BSC", 
    * "customer_ref_id": "USER_123", 
      "description": "" 
    
}'
```

## Query

### Retrieves a specific transaction details

<mark style="color:green;">`POST`</mark> `/v1/order/query`

#### Request Body

| Name          | Type   | Description                                                |
| ------------- | ------ | ---------------------------------------------------------- |
| request\_id\* | String | The external ID of the transaction provided by the partner |
| order\_no     | String | The ID of the transaction to return                        |

200: OK

```json
{    
     "code":"200", 
     "data":{ 
         "order_no":"2022093020000600011063033204", 
         "request_id":"2022093002029700786237858945", 
         "partner_id":"2000061", 
         "currency":"ETH_TEST", 
         "order_type":"charge", 
         "order_amount":"0.100000000000000000", 
         "arrive_amount":"0.099000000000000000", 
         "fee_amount":"0.001000000000000000", 
         "finish_time":"1664519433", 
         "status":99, 
         "reason":"", 
         "metadata":"{ 
               \"txnHash\": \"0x28f0a68ecd8b88700d7bcaeb62f50bd9d58e0cc8a9c29fb3bd6832868eaac428\", 
               \"networkFee\": \"0.000042000000000000\", 
               \"blockHeight\": \"7684865\", 
               \"description\": \"C100005_descETH_TEST\", 
               \"customerRefId\": \"C100005\", 
               \"numOfConfirms\": \"1\", 
               \"sourceAddress\": \"0xCf441129dC8d91B07fB8cb5122570Bfc607eC471\", 
               \"networkCurrency\": \"ETH_TEST\", 
               \"destinationAddress\": \"0xb4df156e6a10F5DB28E701B79E71Bc2F77B97aa1\" 
               }" 
         }, 
   "message":"success" 
} 
```

## Withdraw

### Submits a new crypto withdraw transaction

<mark style="color:green;">`POST`</mark> `/v1/order/withdraw`

#### Request Body

| Name                | Type   | Description                                                                        |
| ------------------- | ------ | ---------------------------------------------------------------------------------- |
| request\_id\*       | String | The external ID of the transaction provided by the partner                         |
| currency\*          | String | The name of crypto asset to withdraw                                               |
| address\*           | String | The destination address to withdraw                                                |
| tag                 | String | The withdraw destination tag for Ripple; memo for EOS/XLM                          |
| amount\*            | String | The requested amount to withdraw                                                   |
| notify\_url         | String | Web-hook url                                                                       |
| customer\_ref\_id\* | String | The ID for the partner to associate the owner of funds(customer) with transactions |
| description         | String | extend info, don't store any sensitive information                                 |

200: OK

```json
{ 
 "data": 
 { 
    "order_no":"2022082020000600101063128149", 
    "request_id":"1660977087787", 
    "partner_id":"2000051", 
    "currency":"USDT_TRC20", 
    "address":"0xCf441129dC8d91B07fB8cb5122570Bfc607eC471", 
    "tag":null, 
    "order_amount":"2.200000000000000000", 
    "arrive_amount":"2.178000000000000000", 
    "fee":"0.022000000000000000", 
    "status":22, 
    "fail_reason":"" 
 }, 
 "code":"200", 
 "message":"Success" 
}
```

#### Code example

```
// Some code 

curl --location --request POST 'https://api.musepay.io/v1/order/withdraw 
--header 'Content-Type: application/json' \ 
--data-raw '{ 
    * "partner_id": "2000001", 
    * "sign_type": "RSA", 
    * "timestamp": "1688371190810", 
    * "nonce": "abccefeafjkjsl", 
    * "sign": "examplesignnotcorrect", 
    * "request_id": "custom_code9982674851738108", 
    * "currency": "USDT_BSC", 
    * "customer_ref_id": "USER_123", 
    * "address": "TWVA2tcuA7124a884xuC199sCX8YpUbHFa", 
    * "amount": "150", 
      "notify_url": "https://notify.url", 
      "description": "" 
    
}'
```

## VerifyDepositAddress

### verify an address whether belong to the musepay platform

<mark style="color:green;">`POST`</mark> `/v1/order/verifyDepositAddress`

#### Request Body

| Name       | Type   | Description                                     |
| ---------- | ------ | ----------------------------------------------- |
| currency\* | String | The name of crypto asset related to the address |
| address\*  | String | The address to verify                           |
| tag        | String | Tag for Ripple; memo for EOS/XLM                |

200: OK

```json
{ 
 "data": 
 { 
    "result": true 
 }, 
 "code":"200", 
 "message":"Success" 
}
```


# Checkout Mode

Hosted Checkout mode is the most recommended integration method. Merchants only need to create orders, redirect to checkout\_url, and handle Webhooks to complete payment integration.

{% hint style="warning" %}
Every request must contain [common parameters](/reference/api-reference/common-parameters)
{% endhint %}

### Create checkout order

<mark style="color:green;">`POST`</mark> `/v1/order/pay`

#### Request Body

| Name                | Type   | Description                                                |
| ------------------- | ------ | ---------------------------------------------------------- |
| request\_id\*       | String | The external ID of the transaction provided by the partner |
| payment\_method\*   | String | The way to pay, values: one of \[on\_line, on\_chain]      |
| amount\*            | String | order amount                                               |
| currency\*          | String | order currency                                             |
| remark              | String | The detail information of product in the checkout page     |
| product\_name\*     | String | The product name to be shown in the checkout page          |
| return\_url         | String | web redirect url when payment is finish, if needed         |
| notify\_url         | String | Web-hook url                                               |
| customer\_ref\_id\* | String | customer unique id                                         |
| pay\_currency       | String | The name of crypto asset to pay                            |

200: OK

```json
{"code":"200", 
 "data":{ 
   "request_id":"1675157000687", 
   "partner_id":"2000051", 
   "order_no":"2023013120000600262092321146", 
   "currency":"USDT_TRC20", 
   "order_amount":"0.3", 
   "status":11, 
   "payment_method":"on_line", 
   "checkout_url":"http://api.dev.xx/v1/qrcode/CnHmkPayhcIFlyat" ,
   "receive_address":"0x5635320sfs4BD3a9cA99bE6e20906Ec53d1Ca65ad" 
 }, 
 "message":"success" 
 }
```


# multiple chain checkout

## Example

{% tabs %}
{% tab title="Crypto order" %}

```bash
curl --location --request POST '/v1/order/pay' \
--header 'Content-Type: application/json' \
--data-raw '{
    * "request_id": "custom_code9982674851738108",
    * "currency": "USDT_BSC", 
    * "amount": "150",
    * "payment_method": "on_line",   
    * "product_name": "product info",
    * "email": "payin@abcpay.io", 
      "notify_url": "https://notify.url",
      "remark": "payout test remark",
    
}'
```

{% endtab %}

{% tab title="Fiat order" %}

```bash
curl --location --request POST '/v1/order/pay' \
--header 'Content-Type: application/json' \
--data-raw '{
    * "request_id": "custom_code9982674851738108",
    * "currency": "IDR",
      "pay_currency": "USDT_BSC", 
    * "amount": "21000",  //fiat amount
    * "payment_method": "on_line",   
    * "product_name": "product info",
      "customer_ref_id": "abc123",
    * "notify_url": "https://notify.url"
    
}'
```

{% endtab %}
{% endtabs %}

```json
// response
{
  "code":"200",
  "data": {
    "request_id":"custom_code9982674851738108",
    "partner_id":"2000051",
    "order_no":"202406173100230009031352048",
    "currency":"USDT_BSC",
    "order_amount":"30",
    "status":22,
    "payment_method":"on_line",
    "receive_address":"0x050b85892F5d5ffffff516868311e7eA2043F",
    "checkout_url":"https://gateway.dev01.musepay.io/mapi/v1/open/qrCode/CnM1mFBzFDtgr0Er"
  },
  "message":"success"
}
```


# specified chain checkout

## Example

```bash
// crypto order
curl --location --request POST '/v1/order/pay' \
--header 'Content-Type: application/json' \
--data-raw '{
    * "request_id": "custom_code9982674851738108",
    * "currency": "USDT_BSC_TEST", 
    * "amount": "150",
    * "payment_method": "on_chain",   
    * "product_name": "product info",
      "customer_ref_id": "abc123",
    * "notify_url": "https://notify.url",
      "remark": ""
    
}'



// Fiat order
curl --location --request POST '/v1/order/pay' \
--header 'Content-Type: application/json' \
--data-raw '{
    * "request_id": "custom_code9982674851738108",
    * "currency": "IDR",
      "pay_currency": "USDT_BSC_TEST", 
    * "amount": "210",
    * "payment_method": "on_chain",   
    * "product_name": "product info",
      "customer_ref_id": "abc123",
    * "notify_url": "https://notify.url"
    
}'
```

```json
// response
{
  "code":"200",
  "data": {
    "request_id":"custom_code9982674851738108",
    "partner_id":"2000051",
    "order_no":"202406173100230009031352048",
    "currency":"USDT_BSC_TEST",
    "order_amount":"30",
    "status":22,
    "payment_method":"on_chain",
    "receive_address":"0x050b85892F5d5ffffff516868311e7eA2043F",
    "checkout_url":"https://gateway.dev01.musepay.io/mapi/v1/open/qrCode/CnM1mFBzFDtgr0Er"
  },
  "message":"success"
}
```


# Query Order

{% hint style="warning" %}
Every request must contain [common parameters](/reference/api-reference/common-parameters)
{% endhint %}

### Retrieves a specific transaction details

<mark style="color:green;">`POST`</mark> `/v1/order/query`

#### Request Body

| Name          | Type   | Description                                                |
| ------------- | ------ | ---------------------------------------------------------- |
| request\_id\* | String | The external ID of the transaction provided by the partner |
| order\_no     | String | The ID of the transaction to return                        |

200: OK

```json
{    
     "code":"200", 
     "data":{ 
         "order_no":"2022093020000600011063033204", 
         "request_id":"2022093002029700786237858945", 
         "partner_id":"2000061", 
         "currency":"ETH_TEST", 
         "order_type":"charge", 
         "order_amount":"0.100000000000000000", 
         "arrive_amount":"0.099000000000000000", 
         "fee_amount":"0.001000000000000000", 
         "finish_time":"1664519433", 
         "status":99, 
         "reason":"", 
         "metadata":"{ 
               \"txnHash\": \"0x28f0a68ecd8b88700d7bcaeb62f50bd9d58e0cc8a9c29fb3bd6832868eaac428\", 
               \"networkFee\": \"0.000042000000000000\", 
               \"blockHeight\": \"7684865\", 
               \"description\": \"C100005_descETH_TEST\", 
               \"customerRefId\": \"C100005\", 
               \"numOfConfirms\": \"1\", 
               \"sourceAddress\": \"0xCf441129dC8d91B07fB8cb5122570Bfc607eC471\", 
               \"networkCurrency\": \"ETH_TEST\", 
               \"destinationAddress\": \"0xb4df156e6a10F5DB28E701B79E71Bc2F77B97aa1\" 
               }" 
         }, 
   "message":"success" 
} 
```


# Fiat Payout API

The Fiat Payout API lets an organization send fiat currency from its USDT balance to a third-party bank account.

{% hint style="info" %}
A successful API response confirms that the request was accepted. Fiat payouts are processed asynchronously. Use the query endpoint or an [order webhook](/webhook/order) to obtain the final result.
{% endhint %}

## Integration Flow

1. [Create a payout quote](/reference/api-reference/fiat-payout-api/quotations) for the destination country and fiat currency.
2. [Create the payout](/reference/api-reference/fiat-payout-api/create-payout) with a valid `customer_quote_no` before the quote expires.
3. [Upload supporting documents](/reference/api-reference/fiat-payout-api/upload-attachment) if they are required for the payout.
4. [Query the payout](/reference/api-reference/fiat-payout-api/query-payout) or process order webhooks until it reaches a final [order status](/enums/order-status).

## Key Rules

| Rule                | Description                                                                                                                                    |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| Quote required      | Every payout must be created from a valid, unexpired quote.                                                                                    |
| Idempotency         | Use a unique `customer_quote_no` and `request_id` for each business request.                                                                   |
| Beneficiary type    | A local payout uses `beneficiary`; an international wire uses either `individual_beneficiary` or `enterprise_beneficiary`, matching the quote. |
| Remittance purpose  | Use a supported `purpose_code` and preserve leading zeroes.                                                                                    |
| Asynchronous status | Creating a payout does not mean it has completed. Use the query API or order webhooks to obtain its final status.                              |

## APIs

| API                                                                                    | Endpoint                              | Description                                            |
| -------------------------------------------------------------------------------------- | ------------------------------------- | ------------------------------------------------------ |
| [Payout Quotations](/reference/api-reference/fiat-payout-api/quotations)               | `/v1/fiatpayout/quotations/create`    | Create a local payout or international wire quote.     |
| [Payout Quotations](/reference/api-reference/fiat-payout-api/quotations)               | `/v1/fiatpayout/quotations/query`     | Query a quote by its MusePay or customer quote number. |
| [Create Fiat Payout](/reference/api-reference/fiat-payout-api/create-payout)           | `/v1/fiatpayout/payouts/create`       | Create a payout from a valid quote.                    |
| [Upload Payout Attachment](/reference/api-reference/fiat-payout-api/upload-attachment) | `/v1/fiatpayout/payouts/files/upload` | Upload a supporting document for a payout.             |
| [Query Fiat Payout](/reference/api-reference/fiat-payout-api/query-payout)             | `/v1/fiatpayout/payouts/query`        | Retrieve a payout and its latest status.               |
| [Remittance Purposes](/reference/api-reference/fiat-payout-api/remittance-purposes)    | `/v1/fiatpayout/payouts/remitReasons` | Retrieve available remittance purpose codes.           |


# Payout Quotations

{% hint style="warning" %}
Every request must contain [common parameters](/reference/api-reference/common-parameters).
{% endhint %}

## Create Payout Quote

Creates a quote for converting USDT into the fiat currency received by the beneficiary.

<mark style="color:green;">`POST`</mark> `/v1/fiatpayout/quotations/create`

### Request Body

| Name                                           | Type   | Required    | Description                                                                                              |
| ---------------------------------------------- | ------ | ----------- | -------------------------------------------------------------------------------------------------------- |
| customer\_quote\_no                            | String | Yes         | Unique quote identifier supplied by the organization. Used as the idempotency key.                       |
| quote\_mode                                    | String | Yes         | Quote mode. Use `source` to specify `pay_amount`, or `dest` to specify `receive_amount`.                 |
| pay\_currency                                  | String | Yes         | Source asset code. Use `USDT` for a payout funded from the USDT balance.                                 |
| pay\_amount                                    | String | Conditional | Amount deducted from the USDT balance. Required when `quote_mode` is `source`.                           |
| beneficiary\_country                           | String | Yes         | Beneficiary country or region as an ISO 3166-1 alpha-2 code.                                             |
| receive\_currency                              | String | Yes         | Fiat currency received by the beneficiary, as an ISO 4217 currency code.                                 |
| receive\_amount                                | String | Conditional | Fiat amount received by the beneficiary. Required when `quote_mode` is `dest`.                           |
| local\_quote                                   | Object | Conditional | Local payout configuration. Provide either `local_quote` or `international_quote`.                       |
| local\_quote.beneficiary\_bank\_id             | String | Yes         | Identifier of the beneficiary bank. Required when `local_quote` is provided.                             |
| international\_quote                           | Object | Conditional | International wire configuration. Provide either `international_quote` or `local_quote`.                 |
| international\_quote.account\_type             | String | Yes         | Beneficiary account type: `01` for an individual or `03` for an organization.                            |
| international\_quote.beneficiary\_relationship | String | Yes         | Beneficiary relationship: `own` for the organization's own account or `third` for a third-party account. |
| international\_quote.bank\_fee\_type           | String | Yes         | Bank fee allocation: `SHA`, `OUR`, or `BEN`.                                                             |

### Request Example

```json
{
  "customer_quote_no": "CUST-QT-001",
  "quote_mode": "source",
  "pay_currency": "USDT",
  "pay_amount": "1000.00",
  "beneficiary_country": "US",
  "receive_currency": "USD",
  "local_quote": {
    "beneficiary_bank_id": "3635"
  }
}
```

### Response Body

| Name                | Type   | Description                                                                        |
| ------------------- | ------ | ---------------------------------------------------------------------------------- |
| customer\_quote\_no | String | Quote identifier supplied by the organization.                                     |
| quote\_no           | String | Quote identifier generated by MusePay.                                             |
| transaction\_time   | Number | Time at which the quote was created, as a 13-digit Unix timestamp in milliseconds. |
| quote\_mode         | String | Quote mode used for the request.                                                   |
| pay\_amount         | String | Amount deducted from the source balance.                                           |
| pay\_currency       | String | Source asset code.                                                                 |
| fee\_amount         | String | Payout fee.                                                                        |
| fee\_currency       | String | Currency in which the fee is charged.                                              |
| exchange\_rate      | String | Exchange rate from `pay_currency` to `receive_currency`.                           |
| receive\_amount     | String | Fiat amount received by the beneficiary.                                           |
| receive\_currency   | String | Beneficiary currency.                                                              |
| expire\_time        | Number | Quote expiration time, as a 13-digit Unix timestamp in milliseconds.               |

```json
{
  "code": "200",
  "message": "success",
  "data": {
    "customer_quote_no": "CUST-QT-001",
    "quote_no": "QT202605050001",
    "transaction_time": 1777946400000,
    "quote_mode": "source",
    "pay_amount": "1000.00",
    "pay_currency": "USDT",
    "fee_amount": "5.00",
    "fee_currency": "USDT",
    "exchange_rate": "1.0000",
    "receive_amount": "995.00",
    "receive_currency": "USD",
    "expire_time": 1777946700000
  }
}
```

## Query Payout Quote

Retrieves a payout quote by its MusePay quote number or the organization's quote identifier.

<mark style="color:green;">`POST`</mark> `/v1/fiatpayout/quotations/query`

### Request Body

| Name                | Type   | Required    | Description                                                                                      |
| ------------------- | ------ | ----------- | ------------------------------------------------------------------------------------------------ |
| quote\_no           | String | Conditional | Quote identifier generated by MusePay. Provide either `quote_no` or `customer_quote_no`.         |
| customer\_quote\_no | String | Conditional | Quote identifier supplied by the organization. Provide either `customer_quote_no` or `quote_no`. |

### Request Example

```json
{
  "quote_no": "QT202605050001"
}
```

The response uses the same `data` object documented under [Create Payout Quote](#create-payout-quote).


# Create Fiat Payout

{% hint style="warning" %}
Every request must contain [common parameters](/reference/api-reference/common-parameters).
{% endhint %}

Creates a local payout or an international wire using a valid payout quote.

<mark style="color:green;">`POST`</mark> `/v1/fiatpayout/payouts/create`

## Request Body

| Name                    | Type   | Required    | Description                                                                                           |
| ----------------------- | ------ | ----------- | ----------------------------------------------------------------------------------------------------- |
| request\_id             | String | Yes         | Unique payout identifier supplied by the organization. Used as the idempotency key.                   |
| customer\_quote\_no     | String | Yes         | `customer_quote_no` used to create the payout quote. The quote must not be expired.                   |
| purpose\_code           | String | Yes         | Remittance purpose code. Preserve leading zeroes.                                                     |
| description             | String | No          | Payout description or reference. Do not include sensitive information.                                |
| beneficiary             | Object | Conditional | Beneficiary for a local payout. Its fields are determined by the selected beneficiary bank.           |
| individual\_beneficiary | Object | Conditional | Individual beneficiary for an international wire. Required when the quote's `account_type` is `01`.   |
| enterprise\_beneficiary | Object | Conditional | Organization beneficiary for an international wire. Required when the quote's `account_type` is `03`. |

For a local payout, provide only `beneficiary`. For an international wire, provide either `individual_beneficiary` or `enterprise_beneficiary`, matching the account type used in the quote.

The idempotency scope is `partner_id + request_id`. A repeated request is rejected and does not create another payout.

### International Beneficiary Fields

The following fields apply to both `individual_beneficiary` and `enterprise_beneficiary`.

| Name                      | Type   | Required | Description                                                                                     |
| ------------------------- | ------ | -------- | ----------------------------------------------------------------------------------------------- |
| account\_no               | String | Yes      | Beneficiary bank account number.                                                                |
| beneficiary\_relationship | String | Yes      | Beneficiary relationship: `own` or `third`. Must match `beneficiary_relationship` in the quote. |
| country                   | String | Yes      | Beneficiary country or region as an ISO 3166-1 alpha-2 code.                                    |
| currency                  | String | Yes      | Beneficiary account currency as an ISO 4217 currency code.                                      |
| bank\_name                | String | Yes      | Beneficiary bank name.                                                                          |
| swift\_code               | String | Yes      | Beneficiary bank SWIFT/BIC.                                                                     |
| address                   | String | Yes      | Beneficiary address.                                                                            |

Additional fields for `individual_beneficiary`:

| Name            | Type   | Required    | Description                                                                                                      |
| --------------- | ------ | ----------- | ---------------------------------------------------------------------------------------------------------------- |
| full\_name      | String | Conditional | Full legal name. May be used for an own-account beneficiary or when a single full-name field is required.        |
| first\_name     | String | Conditional | Given name. Required for a third-party beneficiary unless `full_name` is accepted.                               |
| middle\_name    | String | No          | Middle name.                                                                                                     |
| last\_name      | String | Conditional | Family name. Required for a third-party beneficiary unless `full_name` is accepted.                              |
| nationality     | String | Conditional | Nationality as an ISO 3166-1 alpha-2 code. Required for a third-party beneficiary.                               |
| gender          | String | Conditional | `male` or `female`. Required for a third-party beneficiary when requested by the payout route.                   |
| date\_of\_birth | String | Conditional | Date of birth in `yyyy-MM-dd` format. Required for a third-party beneficiary when requested by the payout route. |

Additional field for `enterprise_beneficiary`:

| Name          | Type   | Required    | Description                                                      |
| ------------- | ------ | ----------- | ---------------------------------------------------------------- |
| company\_name | String | Conditional | Legal organization name. Required for a third-party beneficiary. |

## Request Example

```json
{
  "request_id": "ORD-20260505-001",
  "customer_quote_no": "CUST-QT-001",
  "purpose_code": "10",
  "description": "invoice 1001",
  "beneficiary": {
    "account_no": "1234567890",
    "first_name": "John",
    "last_name": "Smith"
  }
}
```

## Response Body

| Name                | Type   | Description                                                         |
| ------------------- | ------ | ------------------------------------------------------------------- |
| order\_no           | String | Payout order number generated by MusePay.                           |
| request\_id         | String | Payout identifier supplied by the organization.                     |
| pay\_amount         | String | Amount deducted from the source balance.                            |
| pay\_currency       | String | Source asset code.                                                  |
| receive\_currency   | String | Fiat currency received by the beneficiary.                          |
| receive\_amount     | String | Fiat amount received by the beneficiary.                            |
| fee\_amount         | String | Payout fee.                                                         |
| fee\_currency       | String | Currency in which the fee is charged.                               |
| exchange\_rate      | String | Exchange rate applied to the payout.                                |
| exchange\_order\_no | String | Related foreign exchange transaction number.                        |
| status              | Number | Current [order status](/enums/order-status).                        |
| failure\_code       | String | Standard failure code, when available. Returned for failed payouts. |
| failure\_reason     | String | Failure reason, when available. Returned for failed payouts.        |
| create\_time        | Number | Order creation time, as a 13-digit Unix timestamp in milliseconds.  |

```json
{
  "code": "200",
  "message": "success",
  "data": {
    "order_no": "PO202605050001",
    "request_id": "ORD-20260505-001",
    "pay_amount": "1000.00",
    "pay_currency": "USDT",
    "receive_currency": "USD",
    "receive_amount": "995.00",
    "fee_amount": "5.00",
    "fee_currency": "USDT",
    "exchange_rate": "1.0000",
    "exchange_order_no": "EX202605050001",
    "status": 11,
    "create_time": 1777946400000
  }
}
```


# Upload Payout Attachment

{% hint style="warning" %}
Every request must contain [common parameters](/reference/api-reference/common-parameters).
{% endhint %}

Uploads a supporting document for an existing payout order.

<mark style="color:green;">`POST`</mark> `/v1/fiatpayout/payouts/files/upload`

`Content-Type: multipart/form-data`

## Form Data

| Name | Type   | Required | Description                                                                      |
| ---- | ------ | -------- | -------------------------------------------------------------------------------- |
| body | String | Yes      | JSON string containing the common parameters and the payout lookup fields below. |
| file | File   | Yes      | Supporting document for the payout.                                              |

The JSON encoded in `body` contains:

| Name        | Type   | Required    | Description                                                                                |
| ----------- | ------ | ----------- | ------------------------------------------------------------------------------------------ |
| request\_id | String | Conditional | Payout identifier supplied by the organization. Provide either `request_id` or `order_no`. |
| order\_no   | String | Conditional | Payout order number generated by MusePay. Provide either `order_no` or `request_id`.       |

## Body Example

```json
{
  "request_id": "ORD-20260505-001"
}
```

## Response Example

```json
{
  "code": "200",
  "message": "success",
  "data": null
}
```


# Query Fiat Payout

{% hint style="warning" %}
Every request must contain [common parameters](/reference/api-reference/common-parameters).
{% endhint %}

Retrieves a payout order and its latest status.

<mark style="color:green;">`POST`</mark> `/v1/fiatpayout/payouts/query`

## Request Body

| Name        | Type   | Required    | Description                                                                                |
| ----------- | ------ | ----------- | ------------------------------------------------------------------------------------------ |
| request\_id | String | Conditional | Payout identifier supplied by the organization. Provide either `request_id` or `order_no`. |
| order\_no   | String | Conditional | Payout order number generated by MusePay. Provide either `order_no` or `request_id`.       |

## Request Example

```json
{
  "request_id": "ORD-20260505-001"
}
```

## Response Body

| Name                | Type   | Description                                                         |
| ------------------- | ------ | ------------------------------------------------------------------- |
| order\_no           | String | Payout order number generated by MusePay.                           |
| request\_id         | String | Payout identifier supplied by the organization.                     |
| pay\_amount         | String | Amount deducted from the source balance.                            |
| pay\_currency       | String | Source asset code.                                                  |
| receive\_currency   | String | Fiat currency received by the beneficiary.                          |
| receive\_amount     | String | Fiat amount received by the beneficiary.                            |
| fee\_amount         | String | Payout fee.                                                         |
| fee\_currency       | String | Currency in which the fee is charged.                               |
| exchange\_rate      | String | Exchange rate applied to the payout.                                |
| exchange\_order\_no | String | Related foreign exchange transaction number.                        |
| status              | Number | Current [order status](/enums/order-status).                        |
| failure\_code       | String | Standard failure code, when available. Returned for failed payouts. |
| failure\_reason     | String | Failure reason, when available. Returned for failed payouts.        |
| create\_time        | Number | Order creation time, as a 13-digit Unix timestamp in milliseconds.  |

```json
{
  "code": "200",
  "message": "success",
  "data": {
    "order_no": "PO202605050001",
    "request_id": "ORD-20260505-001",
    "pay_amount": "1000.00",
    "pay_currency": "USDT",
    "receive_currency": "USD",
    "receive_amount": "995.00",
    "fee_amount": "5.00",
    "fee_currency": "USDT",
    "exchange_rate": "1.0000",
    "exchange_order_no": "EX202605050001",
    "status": 99,
    "create_time": 1777946400000
  }
}
```

## Payout Status Notifications

MusePay sends an order webhook whenever the payout status changes. The notification uses the standard [order webhook](/webhook/order) payload and the existing [order status](/enums/order-status) values.

Use `order_no` or `request_id` as the idempotency key when processing a notification, and return HTTP `200` after the notification has been processed successfully.


# Remittance Purposes

{% hint style="warning" %}
Every request must contain [common parameters](/reference/api-reference/common-parameters).
{% endhint %}

Returns the remittance purpose codes that can be used to create a payout. Use a code supported by the selected beneficiary bank and preserve leading zeroes.

<mark style="color:green;">`POST`</mark> `/v1/fiatpayout/payouts/remitReasons`

## Response Body

The `data` object maps each remittance purpose code to its description.

```json
{
  "code": "200",
  "message": "success",
  "data": {
    "01": "Transfer to own account",
    "02": "Family support",
    "03": "Education-related student expenses",
    "04": "Medical expenses",
    "05": "Hotel expenses",
    "06": "Travel",
    "07": "Utility bill payments",
    "08": "Loan repayment",
    "09": "Tax payment",
    "10": "Purchase of residential property",
    "11": "Rent payment",
    "12": "Insurance prepayment",
    "13": "Product insurance",
    "14": "Insurance premium payment",
    "15": "Mutual fund investment",
    "16": "Equity investment",
    "17": "Donation",
    "18": "Information service fees",
    "19": "Advertising or public relations expenses",
    "20": "Loyalty service fees, trademark fees, patent fees, and copyright fees",
    "21": "Transaction, guarantee, and factoring fees",
    "22": "Consulting, technical service, academic, and expert fees",
    "23": "Representative office expenses",
    "24": "Building construction costs",
    "25": "Goods transfer fees",
    "26": "Payment for exported goods",
    "27": "Goods logistics fees",
    "28": "General offline trade in goods",
    "29": "Other trade-in-services expenses",
    "30": "Salary or commission payment",
    "31": "Regular maintenance fees",
    "32": "Computer service fees",
    "33": "Small-value remittance",
    "34": "Liberalized remittance",
    "35": "Bonus payment",
    "36": "Influencer fees"
  }
}
```


# Scan Pay API

The Scan-to-Pay API allows your users to use USDT to make payments to commonly used local wallets for everyday transactions.


# ScanPay

{% hint style="warning" %}
Every request must contain [common parameters](/reference/api-reference/common-parameters)
{% endhint %}

{% hint style="info" %}
Demo code can be found at [Github](/reference/api-reference#demo-client)
{% endhint %}

## Submit

This API creates a Scan-to-Pay order, deducts the merchant’s USDT balance, and transfers the funds to the payee account encoded in the QR code.

<mark style="color:green;">`POST`</mark> `/v1/scanPay/submit`

#### Request Body

| Name                                          | Type            | Description                                                                                                             |
| --------------------------------------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------- |
| request\_id<mark style="color:red;">\*</mark> | String          | The external ID of the transaction provided by the partner                                                              |
| user\_xid<mark style="color:red;">\*</mark>   | String (max.20) | The ID for the partner to associate the owner of funds(customer) with transactions                                      |
| qrcode<mark style="color:red;">\*</mark>      | String          | The payment QR code. Currently supports ***Thailand PromptPay**.*                                                       |
| amount<mark style="color:red;">\*</mark>      | String          | The payout amount. If the QR code contains a fixed amount, this value must **match the amount** encoded in the QR code. |
| notify\_url<mark style="color:red;">\*</mark> | String          | Web-hook url                                                                                                            |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    // Response
   "code":200,
   "message":"success",
   "data": {
        "orderNo": "20012332r42723478324",
        "status": 22
    }
}
```

{% endtab %}
{% endtabs %}

<details>

<summary>Code example</summary>

<pre class="language-javascript"><code class="lang-javascript"><strong>// 
</strong>curl --location --request POST 'https://api.musepay.io/v1/scanPay/submit' \
--header 'Content-Type: application/json' \
--data-raw '{
    * "partner_id": "2000001", 
    * "sign_type": "RSA", 
<strong>    * "timestamp": "1688371190810", 
</strong>    * "nonce": "abccefeafjkjsl", 
    * "sign": "examplesignnotcorrect", 
    * "request_id": "abc12347465746", 
    * "user_xid": "USER_123",
    * "qrcode": "00020101021229370016A000000677010111011300666102576555802TH530376454044.22630464C9",
    * "amount": "100",
    * "notify_url": "https://google.com"
}'

</code></pre>

</details>

## Qrcode Info

## Retrieves a specific Qrcode details

<mark style="color:green;">`POST`</mark> `/v1/scanPay/info`

#### Request Body

| Name                                     | Type   | Description                                                                                                                                              |
| ---------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| qrcode<mark style="color:red;">\*</mark> | String | The payment QR code. Currently supports ***Thailand PromptPay**.*                                                                                        |
| amount                                   | String | The payout amount. This value can be null. However, If the QR code contains a fixed amount, this value must **match the amount** encoded in the QR code. |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
  "code": "200",
  "data": {
    "qrcode_type": "prompt_pay",
    "amount": "32",
    "currency": "THB",
    "order_amount": "1.0043942247",
    "order_currency": "USDT",
    "fee_amount": "1",
    "fee_currency": "USDT",
    "exchange_rate": "31.86",
    "beneficiary_name": null,
    "account_type": null,
    "bank_code": null,
    "bank_name": null
  },
  "message": "success"
}
```

{% endtab %}
{% endtabs %}

## Query transaction

## Retrieves a specific transaction details

<mark style="color:green;">`POST`</mark> `/v1/order/query`

#### Request Body

| Name                                          | Type   | Description                                                |
| --------------------------------------------- | ------ | ---------------------------------------------------------- |
| request\_id<mark style="color:red;">\*</mark> | String | The external ID of the transaction provided by the partner |
| order\_no                                     | String | The ID of the transaction to return                        |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{    
     "code":"200",
     "data":{
         "order_no":"2022093020000600011063033204",
         "request_id":"2022093002029700786237858945",
         "partner_id":"2000061",
         "currency":"ETH_TEST",
         "order_type":"proxy_pay",
         "order_amount":"0.100000000000000000",
         "arrive_amount":"0.099000000000000000",
         "fee_amount":"0.001000000000000000",
         "finish_time":"1664519433",
         "status":99,
         "reason":"",
         "metadata":"{
               \"txnHash\": \"0x28f0a68ecd8b88700d7bcaeb62f50bd9d58e0cc8a9c29fb3bd6832868eaac428\", 
               \"networkFee\": \"0.000042000000000000\", 
               \"blockHeight\": \"7684865\", 
               \"description\": \"C100005_descETH_TEST\", 
               \"customerRefId\": \"C100005\", 
               \"numOfConfirms\": \"1\", 
               \"sourceAddress\": \"0xCf441129dC8d91B07fB8cb5122570Bfc607eC471\", 
               \"networkCurrency\": \"ETH_TEST\", 
               \"destinationAddress\": \"0xb4df156e6a10F5DB28E701B79E71Bc2F77B97aa1\"
               }"
         },
   "message":"success"
}


```

{% endtab %}
{% endtabs %}


# WebHook

### Setting up

Setting a web-hook will allow you to get notifications for order status update. You can receive notifications on events in your orders such as incoming/outgoing transactions and transactions status update. The Webhook url can be set up here:

<figure><img src="/files/m35mFB4erBOUJgchAb72" alt=""><figcaption></figcaption></figure>

Once your webHook url is setup, you will start receiving notification on events for your orders. All events will be sent with the following signature.

* **sign** = Base64(*RSA*(PLATFORM\_PRIVATE\_KEY, SHA1(msgBody))

The public key for verifying the signature can be found here:

<figure><img src="/files/SpP7TT4LMI0M4zWkEbNb" alt=""><figcaption></figcaption></figure>

### Data Objects

{% content-ref url="/pages/YR34o8cFBQM9G4YI57ix" %}
[Card](/webhook/card)
{% endcontent-ref %}

{% content-ref url="/pages/5psX8IRbBukTrAaSGU3w" %}
[Order](/webhook/order)
{% endcontent-ref %}

### Retry attempts

MusePay will send a POST request to the URL(s) associated with the partner and expect a 200 response. If no response is received, MusePay will resend the request several more times with an increasing delay between each attempt, the retry attemps will be taken after \[ 0,2,4,8,16,32,64] minutes.<br>


# Order

#### Notify body

<table><thead><tr><th width="193.66666666666666">Parameter</th><th width="118">Type</th><th>Desc</th></tr></thead><tbody><tr><td>partner_id</td><td>String</td><td>The ID of your Account allocated from MusePay.</td></tr><tr><td>order_no</td><td>String</td><td>The ID of the transaction.</td></tr><tr><td>request_id</td><td>String</td><td>The external ID of the transaction provided by the partner.</td></tr><tr><td>order_type</td><td>String</td><td>The transaction type. see <a data-mention href="/pages/Hr7PXNAJzWKwk4HATGd4">/pages/Hr7PXNAJzWKwk4HATGd4</a></td></tr><tr><td>product_code</td><td>String</td><td>The transaction sub-type.</td></tr><tr><td>currency</td><td>String</td><td>The name of crypto asset associated with the transaction.</td></tr><tr><td>order_amount</td><td>String</td><td>The requested order amount.</td></tr><tr><td>pay_amount</td><td>String</td><td>The pay amount actually paid by the user.</td></tr><tr><td>fee_amount</td><td>String</td><td>The service fee amount.</td></tr><tr><td>actual_amount</td><td>String</td><td>The actual amount credited to the merchant.</td></tr><tr><td>finish_time</td><td>String</td><td>The completed time of the transaction.</td></tr><tr><td>status</td><td>Number</td><td>The status of Transaction, see <a data-mention href="/pages/ugnxXePSVXcXtAxZE543">/pages/ugnxXePSVXcXtAxZE543</a></td></tr><tr><td>reason</td><td>String</td><td>The failed reason of transaction.</td></tr><tr><td>sign</td><td>String</td><td>Base64 encoded signature string.</td></tr><tr><td>extra_info</td><td>JSON String</td><td>Protocol / operation specific parameters.</td></tr></tbody></table>

#### Extra Info

<table><thead><tr><th width="200">Parameter</th><th width="120">Type</th><th>Desc</th></tr></thead><tbody><tr><td>description</td><td>String</td><td>extend info from the request.</td></tr><tr><td>txnHash</td><td>String</td><td>Blockchain hash of the transaction</td></tr><tr><td>customerRefId</td><td>String</td><td>The ID for the partner to associate the owner of funds(customer) with transactions</td></tr><tr><td>blockHeight</td><td>Number</td><td>The height (number) of the block the transaction was mined in</td></tr><tr><td>numOfConfirms</td><td>Number</td><td>The number of confirmations of the transaction. The number will increase until the transaction will be considered completed according to the confirmation policy.</td></tr><tr><td>networkFee</td><td>String</td><td>The fee paid to the network</td></tr><tr><td>sourceAddress</td><td>String</td><td>The source address of the transaction</td></tr><tr><td>destinationAddress</td><td>String</td><td>Address where the asset were transferred</td></tr><tr><td>destinationTag</td><td>String</td><td>Destination tag for TON, used as memo for TON</td></tr><tr><td>qrcodeStr</td><td>String</td><td>The payment QR code.</td></tr><tr><td>qrcodeType</td><td>String</td><td>The type of QR code.</td></tr><tr><td>exchangeRate</td><td>String</td><td>The exchange rate of the local fiat currency relative to USDT.</td></tr><tr><td>beneficiaryAccountNumber</td><td>String</td><td>The payee account</td></tr></tbody></table>


# Card

#### **Card Account Transactions**

<table><thead><tr><th width="193.66666666666666">Parameter</th><th width="118">Type</th><th>Desc</th></tr></thead><tbody><tr><td>type</td><td>String</td><td><p><em><strong>APPLY_AUDIT</strong></em>: Card Apply Message <em><strong>CARD_TOP_UP</strong></em>: Card Top-Up Order Message <em><strong>CARD_TO_WALLET</strong></em>: Card To-Wallet Order Message</p><p><em><strong>CARD_BILL_TRANSACTION</strong></em>: Card Bill Transaction Message</p></td></tr><tr><td>data</td><td>Object</td><td>Operation specific message. See <strong>Below</strong>.</td></tr><tr><td>sign</td><td>String</td><td>Base64 encoded signature string.</td></tr></tbody></table>

#### Card Apply Message

<table><thead><tr><th width="193.66666666666666">Parameter</th><th width="118">Type</th><th>Desc</th></tr></thead><tbody><tr><td>applyId</td><td>String</td><td>The ID of the card application.</td></tr><tr><td>request_id</td><td>String</td><td>The external ID of the card apply provided by the partner.</td></tr><tr><td>status</td><td>String</td><td>The status of application, see <a href="/pages/xJ0BienUzG3VF40v3Sen">Apply Status</a></td></tr></tbody></table>

#### Card Order Message

<table><thead><tr><th width="193.66666666666666">Parameter</th><th width="118">Type</th><th>Desc</th></tr></thead><tbody><tr><td>orderNo</td><td>String</td><td>The ID of the transaction.</td></tr><tr><td>requestId</td><td>String</td><td>The external ID of the transaction provided by the partner.</td></tr><tr><td>orderType</td><td>String</td><td>top-up or to-wallet</td></tr><tr><td>orderCurrency</td><td>String</td><td>The currency associated with the card order.</td></tr><tr><td>orderAmount</td><td>String</td><td>The order amount that was proceed to be received.</td></tr><tr><td>fee</td><td>String</td><td>The service fee amount.</td></tr><tr><td>paymentAmount</td><td>String</td><td>The actual amount that was paid.</td></tr><tr><td>feeCurrency</td><td>String</td><td>The fee currency</td></tr><tr><td>status</td><td>String</td><td>The status of Transaction, see <a data-mention href="/pages/EZ0CmuBG8QYHqznQCvF5">/pages/EZ0CmuBG8QYHqznQCvF5</a></td></tr><tr><td>rate</td><td>String</td><td>The exchange rate if involved.</td></tr></tbody></table>

#### Card Bill Transaction Message<br>

<table><thead><tr><th width="210.66666666666666">Parameter</th><th width="125">Type</th><th>Desc</th></tr></thead><tbody><tr><td>detailId</td><td>String</td><td>Card account transaction id</td></tr><tr><td>cardId</td><td>String</td><td>Card id of the card that was used to make the transaction.</td></tr><tr><td>txCreatedAt</td><td>Long</td><td>Date / Time of transaction at which it was initially recorded into the account</td></tr><tr><td>txStatus</td><td>String</td><td><p>The status of the card bill transaction</p><p>. see <a href="/pages/qhyQJr3gHTydf37GzKIq">Transaction Status</a></p></td></tr><tr><td>txPostedAt</td><td>Long</td><td>Date / Time of transaction at which it was posted into the account</td></tr><tr><td>txType</td><td>String</td><td>see <a href="/pages/f9pCLQOGqeRTvRYnBI5E">Transaction Type</a></td></tr><tr><td>txCurrency</td><td>String</td><td>Currency of transaction in card account base currency</td></tr><tr><td>txAmount</td><td>Number</td><td>The service fee amount.</td></tr><tr><td>txMerchant</td><td>Object</td><td>This field will provide information about the merchant where the transaction occurred (for "charge" transactions only).</td></tr><tr><td>txAuthorization</td><td>Object</td><td>Authorization info, applies to <code>charge</code> transactions only</td></tr><tr><td>txEntryType</td><td>String</td><td>The type of entry representing whether the transaction resulted in a credit to or debit from the card account balance.<br>A <code>DEBIT</code> transaction indicates a positive value added to the account (e.g. points reward, refund), while a <code>CREDIT</code> transaction indicates a negative value subtracted from the account balance (e.g. purchase, interest charge).</td></tr></tbody></table>

#### Card Transaction Verify Code Message

*\*only valid for certain cards.*

<table><thead><tr><th width="210.66666666666666">Parameter</th><th width="125">Type</th><th>Desc</th></tr></thead><tbody><tr><td>userId</td><td>Long</td><td>User id</td></tr><tr><td>cardId</td><td>String</td><td>Card id of the card that was used to make the transaction.</td></tr><tr><td>codeToken</td><td>String</td><td>unique token for this message</td></tr><tr><td>codeType</td><td>String</td><td><p>The Type of the verification code:</p><ul><li><strong>OTP</strong> ：<strong>One-Time Password for transaction verification</strong></li><li><strong>OTP_URL：verification url</strong></li><li><strong>OOB : Out-of-Band Verification</strong></li></ul></td></tr><tr><td>codeContent</td><td>Object</td><td>The verification code information</td></tr><tr><td>expireTime</td><td>String</td><td>The verification code expire time</td></tr></tbody></table>


# API Responses

### HTTP Status Code <a href="#http-status-code" id="http-status-code"></a>

* **200** - `OK` - Request processed as expected.
* **400** - `INVALID_REQUEST` - Request is not well-formed, violates schema or incorrect fields.
* **401** - `NOT_AUTHORIZED` - The API key doesn't match the signature or doesn't have permissions to perform the request.
* **403** - `FORBIDDEN` - The API key's permissions doesn't match the needed permission to complete the request.
* **404** - `RESOURCE_NOT_FOUND` - The requested resource doesn't exist.
* **429** - `RATE_LIMIT_REACHED` - Too many requests. Blocked due to rate limiting.
* **5XX** - Something went wrong on MusePay's end

### API Error Codes

<table><thead><tr><th width="130.66666666666666">Error Code</th><th>Constant</th><th>Desc</th></tr></thead><tbody><tr><td>406</td><td>SIGN_ERROR</td><td></td></tr><tr><td>412</td><td>WRONG_TIMESTAMP_OR_NONCE</td><td></td></tr><tr><td>5004</td><td>USER_STATUS_INVALID</td><td></td></tr><tr><td>7000</td><td>ORDER_NOT_EXIST</td><td></td></tr><tr><td>7002</td><td>CURRENCY_NOT_SUPPORT</td><td></td></tr><tr><td>202206</td><td>QUOTA_MIN_CHECK_FAIL</td><td></td></tr><tr><td>202211</td><td>UNSUPPORTED_CURRENCY</td><td></td></tr><tr><td>202224</td><td>DOUBLE_PAYMENT</td><td></td></tr><tr><td>202203</td><td>INSUFFICIENT_BALANCE</td><td></td></tr><tr><td>202212</td><td>ORDER_AMOUNT_MUST_MORE_THAN_SERVICE_FEE</td><td></td></tr><tr><td>2204002</td><td>NO_SPECIFIED_FEE_RULE</td><td></td></tr><tr><td></td><td></td><td></td></tr></tbody></table>


# Enums


# Apply Status

<table><thead><tr><th width="307.5">Value</th><th>Desc</th></tr></thead><tbody><tr><td>APPLYING</td><td>APPLYING</td></tr><tr><td>WAIT_AUDIT</td><td>WAIT_AUDIT</td></tr><tr><td>AUDIT_PASS</td><td>AUDIT_PASS</td></tr><tr><td>CARD_INIT</td><td>CARD_INIT</td></tr><tr><td>AUDIT_REFUSE</td><td>AUDIT_REFUSE</td></tr></tbody></table>


# Card Type

| Value    | Desc                                                                                                                       |
| -------- | -------------------------------------------------------------------------------------------------------------------------- |
| PHYSICAL | a traditional tangible card made of plastic                                                                                |
| VIRTUAL  | a digital version of a physical card that can be used for online transactions or transactions made through a mobile device |


# Card Status

| Value           | Desc            |
| --------------- | --------------- |
| INIT            | INIT            |
| PENDING\_ISSUE  | PENDING\_ISSUE  |
| PENDING\_ACTIVE | PENDING\_ACTIVE |
| ACTIVE          | ACTIVE          |
| LOCK            | LOCK            |
| SUSPENDED       | SUSPENDED       |
| CANCELED        | CANCELED        |


# Card Level

| Value | Desc     |
| ----- | -------- |
| 1     | Platinum |
| 2     | N/A      |
| 3     | N/A      |


# Document Type

| Value | Desc        |
| ----- | ----------- |
| 1     | National-ID |
| 2     | PASSPORT    |


# Kyc Status

| Value | Desc       |
| ----- | ---------- |
| 0     | NOT SET    |
| 1     | WAIT AUDIT |
| 2     | IN AUDIT   |
| 3     | ADOPT/PASS |
| 4     | REFUSE     |


# Card Transaction Type

<table><thead><tr><th width="183">Type</th><th>description</th></tr></thead><tbody><tr><td><strong>charge</strong></td><td>refer to Credit Card consumption transactions</td></tr><tr><td><strong>refund</strong></td><td>refer to Credit Card refund transactions</td></tr><tr><td><strong>top_up</strong></td><td>refer to <strong>MuseWallet</strong> deposit transactions</td></tr><tr><td><strong>repay</strong></td><td>refer to Credit Card repay transactions</td></tr><tr><td><strong>cashback</strong></td><td>refer to Credit Card cashback transactions</td></tr><tr><td><strong>interest</strong></td><td>refer to Credit Card interest transactions</td></tr><tr><td><strong>fee</strong></td><td>refer to Credit Card fee transactions</td></tr><tr><td><strong>other</strong></td><td>refer to Credit Card other transactions</td></tr><tr><td><strong>to_wallet</strong></td><td>refer to <strong>MuseWallet</strong> withdraw transactions</td></tr></tbody></table>


# Card Transaction Status

<table><thead><tr><th width="145">Status Code</th><th>Desc</th></tr></thead><tbody><tr><td>INIT</td><td>The transaction was submitted to the system.</td></tr><tr><td>PENDING</td><td>The transaction is being processed.</td></tr><tr><td>POSTED</td><td>The transaction is successfully completed.</td></tr><tr><td>REJECT</td><td>The transaction has been rejected.</td></tr><tr><td>CANCELED</td><td>The transaction has been cancelled</td></tr></tbody></table>


# Top Up Status

<table><thead><tr><th width="145">Status Code</th><th>Desc</th></tr></thead><tbody><tr><td>INIT</td><td>The transaction was submitted to the system.</td></tr><tr><td>PENDING</td><td>The transaction is being processed.</td></tr><tr><td>SUCCESS</td><td>The transaction is successfully completed.</td></tr><tr><td>FAILED</td><td>The transaction has been failed.</td></tr><tr><td>TIMEOUT</td><td>The transaction has been timeouted</td></tr></tbody></table>


# Order Status

<table><thead><tr><th width="145">Status Code</th><th width="174">Status Constant</th><th>Desc</th></tr></thead><tbody><tr><td>11</td><td>Submitted</td><td>The transaction was submitted to the system.</td></tr><tr><td>22</td><td>Processing</td><td>The transaction is being processed.</td></tr><tr><td>44</td><td>Failed</td><td>The transaction has failed.</td></tr><tr><td>88</td><td>Closed</td><td>The transaction has been cancelled or rejected.</td></tr><tr><td>99</td><td>Success</td><td>The transaction is successfully completed.</td></tr></tbody></table>


# Order Type

<table><thead><tr><th width="183">Type</th><th>description</th></tr></thead><tbody><tr><td><strong>charge</strong></td><td>refer to cryptocurrency <strong>deposit</strong> transactions from wallet-mode</td></tr><tr><td><strong>extract</strong></td><td>refer to cryptocurrency <strong>withdraw</strong> transactions</td></tr><tr><td><strong>pay</strong></td><td>refer to cryptocurrency <strong>payin</strong> transactions from checkout-mode</td></tr><tr><td><strong>proxy_pay</strong></td><td>refer to cryptocurrency <strong>scan-to-pay</strong> transactions</td></tr></tbody></table>