> For the complete documentation index, see [llms.txt](https://docs.maibmerchants.md/e-commerce/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maibmerchants.md/e-commerce/recurring-payments/register-card-in-the-maib-ecomm-system.md).

# Register card in the maib ecomm system

| API endpoint (POST)                                  |
| ---------------------------------------------------- |
| <https://api.maibmerchants.md/v1/savecard-recurring> |

### **Request parameters (body)**

<table><thead><tr><th width="198">Parameter</th><th width="111">Required</th><th width="178">Type</th><th>Description</th></tr></thead><tbody><tr><td>billerExpiry</td><td>YES</td><td>string(4)</td><td><p>The date (month/year) until which the card data will be saved in <strong>maib ecomm</strong> system<strong>.</strong></p><p>Format: <strong>MMYY</strong> (e.g: 1229 -> 31 December 2029 / 23:59:59). </p><p>If the validity of the card is lower than the value passed in this parameter, then the card data will be kept until the date of validity of the card.</p></td></tr><tr><td>clientIp</td><td>YES</td><td>string(15)</td><td>Customer IP</td></tr><tr><td>amount</td><td>NO*</td><td><p>number(decimal)</p><p>≥1</p></td><td><p>Transaction amount. Format: <strong>X.XX</strong></p><p>E.g: <strong>10.25</strong> (currency=USD) means $10 and 25 cents.</p><p></p><p>*If the parameter is passed, the amount will be debited from the Customer's account and the card data will be saved in the <strong>maib ecomm</strong> system.</p><p></p><p>*If the parameter is not passed, then the card data will be saved without debiting anything from the Customer's account.</p></td></tr><tr><td>currency</td><td>YES</td><td>string(3)</td><td>Transaction currency (MDL/EUR/USD).</td></tr><tr><td>language</td><td>YES</td><td>string(2)</td><td><p>Language <strong>maib ecomm checkout</strong> page.</p><p>Allowed values: ro/en/ru</p><p></p></td></tr><tr><td>description</td><td>NO</td><td>string(124)</td><td><p>Payment description.</p><p>Displayed on <strong>maib ecomm checkout</strong> page.</p></td></tr><tr><td>clientName</td><td>NO</td><td>string(128)</td><td>Customer name</td></tr><tr><td>email</td><td>YES</td><td>string(40)</td><td>Customer email</td></tr><tr><td>phone</td><td>NO</td><td>string(40)</td><td>Customer phone</td></tr><tr><td>orderId</td><td>NO</td><td>string(36)</td><td>Order ID generated by Merchant website/app.</td></tr><tr><td>delivery</td><td>NO</td><td>number(decimal)</td><td>Shipping cost</td></tr><tr><td>items</td><td>NO</td><td><p>array</p><p>max. 50 items</p></td><td>The products or services ordered from the website/app.</td></tr><tr><td><ul><li><em>id</em></li></ul></td><td>no</td><td>string(36)</td><td>Product ID</td></tr><tr><td><ul><li><em>name</em></li></ul></td><td>no</td><td>string(128)</td><td>Product name</td></tr><tr><td><ul><li><em>price</em></li></ul></td><td>no</td><td>number(decimal)</td><td>Product price</td></tr><tr><td><ul><li><em>quantity</em> </li></ul></td><td>no</td><td>integer(32)</td><td>Product quantity</td></tr><tr><td>callbackUrl</td><td>NO</td><td>string(2048)</td><td><p>The link where the Merchant will receive the final response with the transaction status and data.</p><p>If this parameter is not passed, its value will be taken from <strong>maibmerchants</strong>. </p></td></tr><tr><td>okUrl</td><td>NO</td><td>string(2048)</td><td><p>The link where the Customer will be redirected if the transaction was successful.</p><p>(GET request: okUrl + payId&#x26;orderId&#x26;billerId)</p><p>If this parameter is not passed, its value will be taken from <strong>maibmerchants</strong>. </p></td></tr><tr><td>failUrl<br></td><td>NO</td><td>string(2048)</td><td><p>The link where the Customer will be redirected if the transaction was failed.</p><p>(GET request: failUrl + payId&#x26;orderId)</p><p>If this parameter is not passed, its value will be taken from <strong>maibmerchants</strong>.</p></td></tr></tbody></table>

**Example**

{% tabs %}
{% tab title="With "amount" parameter" %}

```json
{
"billerExpiry": "1225",
"amount": 6.25,
"currency": "EUR",
"clientIp": "135.250.245.121",
"language": "en",
"description": "Description",
"clientName": "Customer Name",
"email": "customer@gmail.com",
"phone": "069123456",
"orderId": "123",
"delivery": 1.25,
"items": [
{
"id": "10",
"name": "Product 1",
"price": 2.50,
"quantity": 2
}
],
"callbackUrl": "https://example.com/callback",
"okUrl": "https://example.com/ok",
"failUrl": "https://example.com/fail"
}
```

{% endtab %}

{% tab title="Without "amount" parameter" %}

```json
{
"billerExpiry": "1225",
"clientIp": "135.250.245.121",
"currency": "EUR",
"language": "en",
"description": "Description",
"email": "customer@gmail.com",
"phone": "069123456",
"callbackUrl": "https://example.com/callback",
"okUrl": "https://example.com/ok",
"failUrl": "https://example.com/fail"
}
```

{% endtab %}
{% endtabs %}

### **Intermediate response parameters**

<table><thead><tr><th width="189.33333333333331">Parameter</th><th width="114">Type</th><th>Description</th></tr></thead><tbody><tr><td>result</td><td>Object</td><td>Object containing the transaction identifier and redirect link.</td></tr><tr><td><ul><li>payId</li></ul></td><td>String</td><td>Transaction identifier assigned by <strong>maib ecomm</strong></td></tr><tr><td><ul><li>orderId</li></ul></td><td>String</td><td>Order ID generated by Merchant website/app</td></tr><tr><td><ul><li>payUrl</li></ul></td><td>String</td><td>The link to the <strong>maib ecomm checkout</strong> page where the Customer must be redirected to enter their card details (or pay via Apple Pay/Google Pay).</td></tr><tr><td>ok</td><td>Boolean</td><td><p>Request/transaction processing status.</p><p><em>true</em> - no errors;</p><p><em>false -</em> an error occurred (error details will be in <em>errors</em>);</p></td></tr><tr><td>errors</td><td>Array</td><td>Request/transaction processing errors. <a href="/pages/DCjblsWjWxuRYokUtopZ"><mark style="color:blue;">Errors table</mark></a></td></tr><tr><td><ul><li>errorCode</li></ul></td><td>String</td><td>Error code</td></tr><tr><td><ul><li>errorMessage</li></ul></td><td>String</td><td>Error description</td></tr><tr><td><ul><li>errorArgs</li></ul></td><td>Object</td><td>Object contains parameters with error details</td></tr></tbody></table>

**Example**

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

```json
{
"result": {
"payId": "f16a9006-128a-46bc-8e2a-77a6ee99df75",
"orderId": "123",
"payUrl": "https://maib.ecommerce.md/ecomm01/ClientHandler?trans_id=rEsfhyIk8s9ypxkcS9fj/3C8FqA="
},
"ok": true
}
```

{% endtab %}

{% tab title="Error" %}

```json
{
    "errors": [
        {
            "errorCode": "12034",
            "errorMessage": "Parameter 'billerExpiry' has invalid format. Valid format is 'MMYY'",
            "errorArgs": {
                "parameter": "billerExpiry"
            }
        }
    ],
    "ok": false
}
```

{% endtab %}
{% endtabs %}

### **Final response parameters**

<table><thead><tr><th width="222.33333333333331">Parameter</th><th width="120">Type</th><th>Description</th></tr></thead><tbody><tr><td>result</td><td>Object</td><td>Object containing transaction data.</td></tr><tr><td><ul><li>payId</li></ul></td><td>String</td><td>Transaction identifier assigned by <strong>maib ecomm</strong><em><strong>.</strong></em></td></tr><tr><td><ul><li>orderId</li></ul></td><td>String</td><td>Order ID generated by Merchant website/app.</td></tr><tr><td><ul><li>billerId</li></ul></td><td>String</td><td><p>Card identifier saved in <strong>maib ecomm</strong> system.</p><p>The merchant will initiate the following payments by passing this identifier in the request (execute-recurring).</p></td></tr><tr><td><ul><li>billerExpiry</li></ul></td><td>String</td><td><p>The date (month/year) until which the card data will be saved in <strong>maib ecomm</strong> system<strong>.</strong></p><p>Format: <strong>MMYY</strong> (e.g: <strong>1229</strong> - 31 December 2029 / 23:59:59). </p><p>If the validity of the card is lower than the value previously sent in the request, then in the response you will receive the card's expiration date.</p></td></tr><tr><td><ul><li>status</li></ul></td><td>String</td><td><p><a href="/pages/MNTSWn43bFYBkPI948Sp#transaction-status">Transaction status</a></p><p>OK - If the <em>amount</em> parameter has been passed and the transaction is successful (the card data has been registered).</p><p>PENDING - If the <em>amount</em> parameter was not passed (the card data has been registered).</p></td></tr><tr><td><ul><li>statusCode</li></ul></td><td>String</td><td>Transaction status code</td></tr><tr><td><ul><li>statusMessage</li></ul></td><td>String</td><td>Transaction status information message</td></tr><tr><td><ul><li>threeDs</li></ul></td><td>String</td><td><p><a href="/pages/MNTSWn43bFYBkPI948Sp#3d-secure-authentication">3-D Secure authentication result</a></p><p>AUTHENTICATED - successfully authenticated.</p></td></tr><tr><td><ul><li>rrn</li></ul></td><td>String</td><td>RRN - Transaction ID generated by <strong>maib ecomm.</strong></td></tr><tr><td><ul><li>approval</li></ul></td><td>String</td><td>Approval Code - The transaction approval code generated by the card issuing bank.</td></tr><tr><td><ul><li>cardNumber</li></ul></td><td>String</td><td>Masked number card.</td></tr><tr><td><ul><li>amount</li></ul></td><td><p>Number</p><p>(decimal)</p></td><td>Transaction amount. Format: <strong>X.XX</strong></td></tr><tr><td><ul><li>currency</li></ul></td><td>String</td><td>Transaction currency (MDL/EUR/USD)</td></tr><tr><td>signature</td><td>String</td><td>Response validation signature</td></tr></tbody></table>

**Example**

{% tabs %}
{% tab title="With "amount" parameter" %}

```json
{
"result": {
"payId": "f16a9006-128a-46bc-8e2a-77a6ee99df75",
"billerId": "t78i8006-458a-46bc-9e0a-89a6ee11df68",
"billerExpiry": "1225",
"orderId": "123",
"status": "OK",
"statusCode": "000",
"statusMessage": "Approved",
"threeDs": "AUTHENTICATED",
"rrn": "331711380059",
"approval": "327593",
"cardNumber": "510218******1124",
"amount": 6.25,
"currency": "EUR"
},
"signature": "r4KwwIUXQGHhcEM7C4um8o9rSrGEriTRcYQuBbmjEec="
}
```

{% endtab %}

{% tab title="Without "amount" parameter" %}

```json
{
"result": {
"payId": "f16a9006-128a-46bc-8e2a-77a6ee99df75",
"billerId": "t78i8006-458a-46bc-9e0a-89a6ee11df68",
"billerExpiry": "1225",
"status": "PENDING",
"threeDs": "AUTHENTICATED",
"cardNumber": "510218******1124",
"amount": 0,
"currency": "EUR"
},
"signature": "r4KwwIUXQGHhcEM7C4um8o9rSrGEriTRcYQuBbmjEec="
}
```

{% endtab %}
{% endtabs %}