# 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.&#x20;

{% 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-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#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-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/dgRfWhBgqJT3XxhOdqDU" 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#confirm-transaction) — to confirm the transaction.
   * POST [/txn-verification-decline](/reference/api-reference/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 %}

## User

create and query order information .

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

## Card

Retrieve balance information on a specific crypto currency.

{% content-ref url="/pages/v6vSf9ZeAunBJXS0iXUn" %}
[Card User](/reference/api-reference/card-user)
{% 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>


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

{% 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" : {
    *     "last_name": "Weather",
    *     "first_name": "Jack",
    *     "date_of_birth": "1988-02-02",
          "occupation": "01",
          "annual_income":"100000"
      },
      "document": {
    *     "type": "passport",
    *     "front": "afjkfjkasfjajsdfkasfjadsf",
    *     "back": "afjkfjkasfjajsdfkasfjasdafasf",
    *     "number": "G012345678",
    *     "country": "China",
    *     "expiry_date": "2030-10-10"
      },
      "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                                                                                                                                                                                              |
| ------------------------------------------------------------ | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| individual.annual\_income                                    | String | Annual income of card holder in card currency                                                                                                                                                            |
| individual.date\_of\_birth<mark style="color:red;">\*</mark> | String | Date of birth (YYYY-MM-DD)                                                                                                                                                                               |
| 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.occupation                                        | String | Occupation of card holder.                                                                                                                                                                               |
| document<mark style="color:red;">\*</mark>                   | Object | Government Issued Identification Document Information                                                                                                                                                    |
| 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.                                                                                                                                                             |
| document.country<mark style="color:red;">\*</mark>           | String | Issuing country of identification document in ISO3166-1 alpha-2 format                                                                                                                                   |
| document.number<mark style="color:red;">\*</mark>            | String | Identification document number.                                                                                                                                                                          |
| document.back                                                | String | <p>The back of a document file encoded in data URI base64 encoded format.</p><p></p><p>The back of a document file encoded in data URI base64 encoded format</p>                                         |
| 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></p><p>The following mime types are accepted for ID documents:<br>image/jpeg,<br>image/png.</p><p></p> |
| document.type<mark style="color:red;">\*</mark>              | String | 1 or 2, enums in [Document Type](/enums/document-type)                                                                                                                                                   |
| document.expiry\_date<mark style="color:red;">\*</mark>      | String | Expiry date of identification document (YYYY-MM-DD)                                                                                                                                                      |
| address                                                      | Object | Delivery address                                                                                                                                                                                         |
| address.details                                              | String | Detail delivery address                                                                                                                                                                                  |
| address.city                                                 | String | Delivery city                                                                                                                                                                                            |
| address.country                                              | String | Delivery country of identification document in ISO3166-1 alpha-2 format                                                                                                                                  |
| address.post\_code                                           | String | Delivery post code                                                                                                                                                                                       |

{% 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.&#x20;

#### 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:

`{`&#x20;

&#x20;   `"card_id": "akflf51b3",`&#x20;

&#x20;   `"card_number": "4242424212341234",`&#x20;

&#x20;   `"expiry_month": "11",`&#x20;

&#x20;   `"expiry_year": "2028",`&#x20;

&#x20;   `"security_code": "001"`&#x20;

`}`

#### 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 %}


# 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 %}


# 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 Address

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

Query the 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 %}


# 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-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**&#x20;

<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**&#x20;

<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`&#x20;

#### 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 %}


# ScanPay

This chapter provides the API specifications for creating and querying Scan-to-Pay orders.

{% 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 %}

## &#x20;Submit&#x20;

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.&#x20;

* **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/f9pCLQOGqeRTvRYnBI5E">/pages/f9pCLQOGqeRTvRYnBI5E</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 amount.</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 that was proceed to received.</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/qhyQJr3gHTydf37GzKIq">/pages/qhyQJr3gHTydf37GzKIq</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 XRP, used as memo for EOS/XLM</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>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 </td></tr><tr><td><strong>proxy_pay</strong></td><td>refer to cryptocurrency <strong>scan-to-pay</strong> transactions </td></tr></tbody></table>