Merchant API Reference

https://docs.paymentplatform.dev/merchant-api-reference
Admin
This API provides a RESTful interface for merchants to manage transactions, including credit card...
Tokens:116,072
Snippets:204
Trust Score:4.5
Update:9 months ago
Show doc for...
Tokens:
Raw
### Install Payengine Library via npm

Source: https://docs.paymentplatform.dev/merchant-api-reference/secure-fields/secure-fields-overview

Provides the bash command to install the payengine library from the npm public registry. This is the recommended method for integrating the Platform library.

```bash
npm install --save payengine
```

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

### 3D Secure Response Example

Source: https://docs.paymentplatform.dev/merchant-api-reference/transactions/credit-card-authorization-v2

This example shows a response indicating that a 3D Secure action is required for the transaction, including the type of authentication and status.

```APIDOC
## GET /websites/paymentplatform_dev_merchant-api-reference

### Description
This endpoint provides an example of a 3D Secure response, indicating whether an action is required, the type of 3DS authentication, and its status.

### Method
GET

### Endpoint
/websites/paymentplatform_dev_merchant-api-reference

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{
    "data": {
        "ID": "75764256-ba64-45cf-8ffe-9d8eee450116",
        "TransactionID": "70fb1318-fb90-4a0e-a5e8-3e5875c15e21",
        "MerchantID": "8357832f-79c9-48fd-9647-d1dae251e434",
        "description": "Payment for the service",
        "ThreeDSActionRequired": false,
        "ThreeDSType": "frictionless",
        "ThreeDSStatus": "succeeded",
        "ThreeDSData": "eyJ0IjoiNzBmYjEzMTgtZmI5MC00YTBlLWE1ZTgtM2U1ODc1YzE1ZTIxIiwiZSI6InNhbmRib3giLCJzIjoiMjAyMy0wNi0xMVQwNzo1NzowMC42NDlaIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiIyNTZlOTUxMi1lNDNmLTRjZDUtOWFhNy0zOGU5MDZjZWU2MWUiLCJ0aHJlZURTTWV0aG9kVVJMIjoiaHR0cHM6Ly9hY3Muc2FuZGJveC4zZHNlY3VyZS5pby8zZHNtZXRob2QifQ",
        "AuthResponse": {
            "status": "PENDING_3DSAUTH"
        }
    }
}
```

### Response
#### Success Response (200)
- **data** (object) - Contains the details of the 3D Secure authentication.
  - **ID** (string) - Unique identifier for the transaction record.
  - **TransactionID** (string) - Unique identifier for the payment transaction.
  - **MerchantID** (string) - Unique identifier for the merchant.
  - **description** (string) - Description of the payment.
  - **ThreeDSActionRequired** (boolean) - Indicates if a 3D Secure action is required.
  - **ThreeDSType** (string) - The type of 3D Secure authentication (e.g., "frictionless", "challenge").
  - **ThreeDSStatus** (string) - The status of the 3D Secure authentication (e.g., "succeeded", "failed", "pending").
  - **ThreeDSData** (string) - Encrypted data related to the 3D Secure authentication.
  - **AuthResponse** (object) - Details of the authorization response.
    - **status** (string) - Authorization status, which may be "PENDING_3DSAUTH" if 3DS is in progress.

#### Response Example
```json
{
    "data": {
        "ID": "75764256-ba64-45cf-8ffe-9d8eee450116",
        "TransactionID": "70fb1318-fb90-4a0e-a5e8-3e5875c15e21",
        "MerchantID": "8357832f-79c9-48fd-9647-d1dae251e434",
        "description": "Payment for the service",
        "ThreeDSActionRequired": false,
        "ThreeDSType": "frictionless",
        "ThreeDSStatus": "succeeded",
        "ThreeDSData": "eyJ0IjoiNzBmYjEzMTgtZmI5MC00YTBlLWE1ZTgtM2U1ODc1YzE1ZTIxIiwiZSI6InNhbmRib3giLCJzIjoiMjAyMy0wNi0xMVQwNzo1NzowMC42NDlaIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiIyNTZlOTUxMi1lNDNmLTRjZDUtOWFhNy0zOGU5MDZjZWU2MWUiLCJ0aHJlZURTTWV0aG9kVVJMIjoiaHR0cHM6Ly9hY3Muc2FuZGJveC4zZHNlY3VyZS5pby8zZHNtZXRob2QifQ",
        "AuthResponse": {
            "status": "PENDING_3DSAUTH"
        }
    }
}
```
```

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

### Payment Request Examples (JavaScript)

Source: https://docs.paymentplatform.dev/merchant-api-reference/transactions/credit-card-sale

Demonstrates various payment request structures using JavaScript. These examples cover basic transactions, 3DS authentication, metadata inclusion, itemized purchases, additional data, and optional Kount data.

```javascript
{
    "merchant_id": "a447b0b8-0dbb-4e07-bfc2-c35bba8d71e8",
    "data": {
        "transactionAmount": "110.00",
        "cardToken": "card_sandbox_xxxx",
        "store_payment_method": true,
        "initiated_by": "customer",
        "order_number": "Order124",
        "description": "Payment for the services",
        "customer_name": "John Doe",
        "ip_address": "10.10.10.10",
        "sales_tax": "10",
        "gratuity": "10.00",
        "internalTransactionID": "987654321",
        "currencyCode": "USD"
    }
}
```

```javascript
{
    "merchant_id": "a447b0b8-0dbb-4e07-bfc2-c35bba8d71e8",
    "attempt3DSecure": true,
    "browserInfo": "COLLECTED USING CLIENT BROWSER",    
    "data": {
        "transactionAmount": "110.00",
        "cardToken": "card_sandbox_xxxx",
        "description": "Payment for the services"
    }
}
```

```javascript
{
    "merchant_id": "a447b0b8-0dbb-4e07-bfc2-c35bba8d71e8",
    "data": {
        "transactionAmount": "110.00",
        "cardToken": "card_sandbox_xxxx",
        "description": "Payment for the services",
        "metadata": {
            "customerId": "123",
            "email": "test@test.com"
        }
    }
}
```

```javascript
{
    "merchant_id": "a447b0b8-0dbb-4e07-bfc2-c35bba8d71e8",
    "attempt3DSecure": true,
    "browserInfo": "COLLECTED USING CLIENT BROWSER",    
    "data": {
        "transactionAmount": "200.20",
        "cardToken": "card_sandbox_xxxx",
        "description": "Payment for the services",
        "items": [
          {
              "id" : "Item123",
              "name": "sample",
              "unitCost": "95.00",
              "quantity": 2,
              "totalAmount": "190.00" //included in the transaction amount
            }
         ],
         "sales_tax": "10.00",
         "other_tax": [
             {
                 "name": "CRV",
                 "amount": "0.20"
             }
         ]
    }
}
```

```javascript
{
    "merchant_id": "a447b0b8-0dbb-4e07-bfc2-c35bba8d71e8",
    "data": {
        "transactionAmount": "110.00",
        "cardToken": "card_sandbox_xxxx",
        "Description": "Payment for the services",
        "additionalData": {
            "loanNumber": "L255525"
        },
        "metadata": {
            "customerId": "123",
            "email" : "test@test.com"
        }
    }
}
```

```javascript
{
    "merchant_id": "a447b0b8-0dbb-4e07-bfc2-c35bba8d71e8",
    "data": {
        "transactionAmount": "110.00",
        "cardToken": "card_sandbox_xxxx",
        "Description": "Payment for the services",
        "additionalData": {
            "loanNumber": "L255525"
        },
        "kount": {
              "user_defined_fields": {
              "fieldName1": "Value1",
              "fieldName2": "Value2"
          },
        }
    }
}
```

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

### Payment Transaction Response Example

Source: https://docs.paymentplatform.dev/merchant-api-reference/transactions/credit-card-authorization-v2

This example demonstrates a typical response for a payment transaction, including details about the transaction, authorization, and customer receipts.

```APIDOC
## GET /websites/paymentplatform_dev_merchant-api-reference

### Description
This endpoint provides an example of a successful payment transaction response, detailing the transaction ID, merchant information, authorization status, and receipt data.

### Method
GET

### Endpoint
/websites/paymentplatform_dev_merchant-api-reference

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{
    "data": {
        "ID": "78451f08-7b10-480f-b811-75014ddcaf53",
        "TransactionID": "4dd6b470-91d6-4ec4-b36b-cc4a96a2fd51",
        "MerchantID": "e6705370-fccc-4bfb-9fb4-0e8a0a0cf426",
        "Description": "Payment for the services",
        "AuthResponse": {
            "status": "PASS",
            "responseCode": "A0000",
            "responseMessage": "Success",
            "authCode": "387263",
            "hostResponseCode": "00",
            "hostReferenceNumber": "347535209284",
            "taskID": "18012509",
            "transactionID": "85860483",
            "transactionTimestamp": "2025-03-31T07:02:00",
            "transactionAmount": "200.20",
            "processedAmount": "200.20",
            "totalAmount": "200.20",
            "addressVerificationCode": "X",
            "cardHolderVerificationCode": "N",
            "cardType": "visa",
            "maskedCardNumber": "4242",
            "customerReceipt": "\n\nSandbox Merchant\n200 Epcot Center Dr\nOrlando, FL 32836\n800-490-8514\n\nCREDIT CARD\n\nSampleUSD $190.00\n2 @ $95.00\n\nSUBTOTAL: USD $190.00\nCRV:USD $0.20\n---------------------------------------------------------------\nTOTAL TAX:USD $0.20\nTOTAL (1 ITEM)USD $200.20\n\nVISA ************4242\nDATE & TIME:03-31-25 12:02:00\nREC #: \nTYPE: AUTH\nDESCRIPTION: Payment for the services\n\nTOTAL: USD $200.20\nDECLINED\nNO SIGNATURE REQUIRED\nTHANK YOU\nCardholder Copy\nRetain this copy for statement verification.\n\n\n\n\n\n\n\n",
            "merchantReceipt": "\n\nSandbox Merchant\n200 Epcot Center Dr\nOrlando, FL 32836\n800-490-8514\n\nCREDIT CARD\n\nSampleUSD $190.00\n2 @ $95.00\n\nSUBTOTAL: USD $190.00\nCRV:USD $0.20\n---------------------------------------------------------------\nTOTAL TAX:USD $0.20\nTOTAL (1 ITEM)USD $200.20\n\nVISA ************4242\nDATE & TIME:03-31-25 12:02:00\nREC #: \nTYPE: AUTH\nDESCRIPTION: Payment for the services\n\nTOTAL: USD $200.20\nDECLINED\nX_______________________
I AGREE TO PAY ABOVE TOTAL AMOUNT IN ACCORDANCE WITH CARD ISSUER's AGREEMENT (MERCHANT AGREEMENT IF CREDIT VOUCHER)\nTHANK YOU\nMerchant Copy\nRetain this copy for statement verification.\n\n\n\n\n\n\n\n",
            "partialPayment": false
        },
        "Metadata": {
            "customerId": "123",
            "email": "test@test.com"
        },
        "token": "card_sandbox_tE8BT9Betjsp7PV46IS9xb1c"
    }
}
```

### Response
#### Success Response (200)
- **data** (object) - Contains the details of the payment transaction.
  - **ID** (string) - Unique identifier for the transaction record.
  - **TransactionID** (string) - Unique identifier for the payment transaction.
  - **MerchantID** (string) - Unique identifier for the merchant.
  - **Description** (string) - Description of the payment.
  - **AuthResponse** (object) - Details of the authorization response.
    - **status** (string) - Authorization status (e.g., "PASS", "FAIL").
    - **responseCode** (string) - Response code from the authorization.
    - **responseMessage** (string) - Message associated with the response code.
    - **authCode** (string) - Authorization code provided by the issuer.
    - **hostResponseCode** (string) - Response code from the payment host.
    - **hostReferenceNumber** (string) - Reference number from the payment host.
    - **taskID** (string) - Task identifier.
    - **transactionID** (string) - Transaction identifier from the host.
    - **transactionTimestamp** (string) - Timestamp of the transaction.
    - **transactionAmount** (string) - The amount of the transaction.
    - **processedAmount** (string) - The amount that was processed.
    - **totalAmount** (string) - The total amount including taxes and fees.
    - **addressVerificationCode** (string) - AVS response code.
    - **cardHolderVerificationCode** (string) - CVV response code.
    - **cardType** (string) - Type of card used (e.g., "visa").
    - **maskedCardNumber** (string) - Masked card number (e.g., "4242").
    - **customerReceipt** (string) - Formatted customer receipt text.
    - **merchantReceipt** (string) - Formatted merchant receipt text.
    - **partialPayment** (boolean) - Indicates if the payment was partial.
  - **Metadata** (object) - Additional metadata associated with the transaction.
    - **customerId** (string) - Identifier for the customer.
    - **email** (string) - Customer's email address.
  - **token** (string) - Token representing the card used for the transaction.

#### Response Example
```json
{
    "data": {
        "ID": "78451f08-7b10-480f-b811-75014ddcaf53",
        "TransactionID": "4dd6b470-91d6-4ec4-b36b-cc4a96a2fd51",
        "MerchantID": "e6705370-fccc-4bfb-9fb4-0e8a0a0cf426",
        "Description": "Payment for the services",
        "AuthResponse": {
            "status": "PASS",
            "responseCode": "A0000",
            "responseMessage": "Success",
            "authCode": "387263",
            "hostResponseCode": "00",
            "hostReferenceNumber": "347535209284",
            "taskID": "18012509",
            "transactionID": "85860483",
            "transactionTimestamp": "2025-03-31T07:02:00",
            "transactionAmount": "200.20",
            "processedAmount": "200.20",
            "totalAmount": "200.20",
            "addressVerificationCode": "X",
            "cardHolderVerificationCode": "N",
            "cardType": "visa",
            "maskedCardNumber": "4242",
            "customerReceipt": "\n\nSandbox Merchant\n200 Epcot Center Dr\nOrlando, FL 32836\n800-490-8514\n\nCREDIT CARD\n\nSampleUSD $190.00\n2 @ $95.00\n\nSUBTOTAL: USD $190.00\nCRV:USD $0.20\n---------------------------------------------------------------\nTOTAL TAX:USD $0.20\nTOTAL (1 ITEM)USD $200.20\n\nVISA ************4242\nDATE & TIME:03-31-25 12:02:00\nREC #: \nTYPE: AUTH\nDESCRIPTION: Payment for the services\n\nTOTAL: USD $200.20\nDECLINED\nNO SIGNATURE REQUIRED\nTHANK YOU\nCardholder Copy\nRetain this copy for statement verification.\n\n\n\n\n\n\n\n",
            "merchantReceipt": "\n\nSandbox Merchant\n200 Epcot Center Dr\nOrlando, FL 32836\n800-490-8514\n\nCREDIT CARD\n\nSampleUSD $190.00\n2 @ $95.00\n\nSUBTOTAL: USD $190.00\nCRV:USD $0.20\n---------------------------------------------------------------\nTOTAL TAX:USD $0.20\nTOTAL (1 ITEM)USD $200.20\n\nVISA ************4242\nDATE & TIME:03-31-25 12:02:00\nREC #: \nTYPE: AUTH\nDESCRIPTION: Payment for the services\n\nTOTAL: USD $200.20\nDECLINED\nX_______________________
I AGREE TO PAY ABOVE TOTAL AMOUNT IN ACCORDANCE WITH CARD ISSUER's AGREEMENT (MERCHANT AGREEMENT IF CREDIT VOUCHER)\nTHANK YOU\nMerchant Copy\nRetain this copy for statement verification.\n\n\n\n\n\n\n\n",
            "partialPayment": false
        },
        "Metadata": {
            "customerId": "123",
            "email": "test@test.com"
        },
        "token": "card_sandbox_tE8BT9Betjsp7PV46IS9xb1c"
    }
}
```
```

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

### Transaction Processing Example

Source: https://docs.paymentplatform.dev/merchant-api-reference/transactions/credit-card-sale

This snippet demonstrates a typical successful response for a payment transaction, including detailed sale information and metadata.

```APIDOC
## POST /transactions

### Description
Processes a payment transaction for a merchant.

### Method
POST

### Endpoint
/transactions

### Parameters
#### Request Body
- **payment_details** (object) - Required - Details of the payment to be processed.
  - **amount** (string) - Required - The transaction amount.
  - **currency** (string) - Required - The currency code (e.g., USD).
  - **card_token** (string) - Required - The token representing the card details.
  - **order_id** (string) - Optional - The merchant's order number.
  - **metadata** (object) - Optional - Additional key-value pairs for metadata.
    - **customerId** (string) - Optional - The customer's ID.
    - **email** (string) - Optional - The customer's email address.

### Request Example
```json
{
  "payment_details": {
    "amount": "110.00",
    "currency": "USD",
    "card_token": "card_sandbox_8Aq30HAc8TLFUFvTjqwo556i",
    "order_id": "Order124",
    "metadata": {
      "customerId": "123",
      "email": "test@test.com"
    }
  }
}
```

### Response
#### Success Response (200)
- **data** (object) - Contains the transaction details.
  - **ID** (string) - Unique identifier for the transaction.
  - **TransactionID** (string) - Gateway-specific transaction identifier.
  - **MerchantID** (string) - Identifier for the merchant.
  - **gateway_id** (string) - Identifier for the payment gateway.
  - **ThreeDSActionRequired** (boolean) - Indicates if 3D Secure action is required.
  - **internalTransactionID** (string) - Internal system transaction ID.
  - **SaleResponse** (object) - Details of the sale response.
    - **status** (string) - Transaction status (e.g., PASS, FAIL).
    - **responseCode** (string) - Gateway response code.
    - **responseMessage** (string) - Human-readable response message.
    - **authCode** (string) - Authorization code from the bank.
    - **hostResponseCode** (string) - Response code from the host processor.
    - **hostReferenceNumber** (string) - Reference number from the host processor.
    - **taskID** (string) - Task identifier.
    - **transactionID** (string) - Transaction identifier from the gateway.
    - **transactionTimestamp** (string) - Timestamp of the transaction.
    - **transactionAmount** (string) - The amount of the transaction.
    - **processedAmount** (string) - The amount that was processed.
    - **totalAmount** (string) - The total amount including taxes.
    - **addressVerificationCode** (string) - AVS response code.
    - **cardHolderVerificationCode** (string) - CVV response code.
    - **cardType** (string) - Type of card used (e.g., visa).
    - **maskedCardNumber** (string) - Masked card number.
    - **customerReceipt** (string) - Formatted customer receipt.
    - **merchantReceipt** (string) - Formatted merchant receipt.
    - **partialPayment** (boolean) - Indicates if it was a partial payment.
  - **Description** (string) - Description of the transaction.
  - **Metadata** (object) - Metadata associated with the transaction.
    - **customerId** (string) - The customer's ID.
    - **email** (string) - The customer's email address.
  - **token** (string) - Token generated for the transaction.
  - **order_number** (string) - The merchant's order number.
  - **sales_tax** (string) - The sales tax amount.
  - **customer_name** (string) - The name of the customer.
  - **currencyCode** (string) - The currency code.

#### Response Example
```json
{
    "data": {
        "ID": "62430b78-3049-4d25-9637-b78f3ea16709",
        "TransactionID": "8760a4f8-51fd-46eb-a3b4-32f08e05e487",
        "MerchantID": "1e4e6029-2cc9-4b2c-87c1-7a4b2af6d6c6",
        "gateway_id": "1f3e0f67-d560-494c-bb1a-97558a462cc5",
        "ThreeDSActionRequired": false,
        "internalTransactionID": "987654321",
        "SaleResponse": {
            "status": "PASS",
            "responseCode": "A0000",
            "responseMessage": "Success",
            "authCode": "165201",
            "hostResponseCode": "00",
            "hostReferenceNumber": "990551169365",
            "taskID": "90687488",
            "transactionID": "69832290",
            "transactionTimestamp": "2025-04-02T17:49:08",
            "transactionAmount": "110.00",
            "processedAmount": "110.00",
            "totalAmount": "110.00",
            "addressVerificationCode": "X",
            "cardHolderVerificationCode": "N",
            "cardType": "visa",
            "maskedCardNumber": "1111",
            "customerReceipt": "        Sandbox US Merchant         \n        200 Epcot Center Dr         \n         Orlando, FL 32836          \n            800-490-8514            \n                 \n                 \n        2025-04-02 05:49 PM         \n           CREDIT - SALE            \n         Entry Mode : KEYED         \n      Transaction ID: 69832290      \n      Invoice Number: Order124      \nDescription: Payment for the service\n                 s                  \n       SUBTOTAL: USD $100.00        \n       SALES TAX: USD $10.00        \n         TOTAL: USD $110.00         \n                 \n                 \n       NO SIGNATURE REQUIRED        \n              APPROVED              \n                 \n                 \n                 \n                 \n                 \n                 \n                 \n                 \n                 \n                 \n           Customer Copy            \n",
            "merchantReceipt": "        Sandbox US Merchant         \n        200 Epcot Center Dr         \n         Orlando, FL 32836          \n            800-490-8514            \n                 \n                 \n        2025-04-02 05:49 PM         \n           CREDIT - SALE            \n         Entry Mode : KEYED         \n      Transaction ID: 69832290      \n      Invoice Number: Order124      \nDescription: Payment for the service\n                 s                  \n       SUBTOTAL: USD $100.00        \n       SALES TAX: USD $10.00        \n         TOTAL: USD $110.00         \n                 \n                 \n      X_______________________      \nI AGREE TO PAY ABOVE TOTAL AMOUNT IN\n ACCORDANCE WITH CARD ISSUER's AGREE\nMENT (MERCHANT AGREEMENT IF CREDIT V\n              OUCHER)               \n     KEEP COPY FOR YOUR RECORDS     \n               \n \n                \n              APPROVED              \n                 \n                 \n                 \n                 \n                 \n                 \n                 \n                 \n                 \n                 \n           Merchant Copy            \n",
            "partialPayment": false
        },
        "Description": "Payment for the services",
        "Metadata": {
            "customerId": "123",
            "email": "test@test.com"
        },
        "token": "card_sandbox_8Aq30HAc8TLFUFvTjqwo556i",
        "order_number": "Order124",
        "sales_tax": "10",
        "customer_name": "John Doe",
        "currencyCode": "USD"
    }
}
```
```

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

### Transaction Refund Response Example

Source: https://docs.paymentplatform.dev/merchant-api-reference/transactions/refund

This snippet shows an example of a successful refund transaction response, detailing the returned amount, transaction IDs, and customer/merchant receipt information.

```APIDOC
## GET /transactions/{transactionId}/refund

### Description
Retrieves details of a specific refunded transaction.

### Method
GET

### Endpoint
`/transactions/{transactionId}/refund`

### Parameters
#### Path Parameters
- **transactionId** (string) - Required - The unique identifier of the transaction to retrieve refund details for.

### Request Example
```json
{
  "example": "No request body needed for GET request."
}
```

### Response
#### Success Response (200)
- **data** (object) - Contains the transaction details.
  - **ID** (string) - Unique ID for the refund record.
  - **MerchantID** (string) - The ID of the merchant.
  - **TransactionID** (string) - The original transaction ID associated with the refund.
  - **reason** (string) - The reason for the refund.
  - **internalTransactionID** (string) - Internal system transaction ID.
  - **token** (string) - Token associated with the transaction.
  - **ReturnResponse** (object) - Details of the refund processing response.
    - **status** (string) - Processing status (e.g., PASS, FAIL).
    - **responseCode** (string) - Response code from the payment processor.
    - **responseMessage** (string) - Human-readable message for the response code.
    - **authCode** (string) - Authorization code, if applicable.
    - **hostResponseCode** (string) - Response code from the host system.
    - **hostReferenceNumber** (string) - Reference number from the host system.
    - **taskID** (string) - Task identifier.
    - **transactionID** (string) - Transaction ID from the host system.
    - **transactionTimestamp** (string) - Timestamp of the transaction.
    - **orderNumber** (string) - Order number associated with the transaction.
    - **processedAmount** (string) - The amount that was processed for the refund.
    - **externalReferenceID** (string) - External reference ID.
    - **customerReceipt** (string) - Formatted receipt for the customer.
    - **merchantReceipt** (string) - Formatted receipt for the merchant.
    - **maskedCardNumber** (string) - Masked card number used for the transaction.
    - **cardType** (string) - Type of card used (e.g., visa).
    - **bank_routing_number** (string) - Bank routing number (present for ACH).
    - **masked_bank_account** (string) - Masked bank account number (present for ACH).
    - **returnedAmount** (string) - The amount that was returned.
  - **Metadata** (object) - Additional metadata for the transaction.
    - **customerId** (string) - Customer identifier.
    - **email** (string) - Customer email address.
  - **order_number** (string) - Order number.
  - **device** (object) - Information about the device used for the transaction.
    - **id** (string) - Device ID.
    - **type** (string) - Device type.
    - **name** (string) - Device name.
    - **model** (string) - Device model.
    - **serial_number** (string) - Device serial number.
    - **sdk_version** (string) - SDK version used.
    - **manufacturer** (string) - Device manufacturer.
    - **app_version** (string) - Application version.
    - **os** (string) - Operating system.
    - **os_version** (string) - Operating system version.

#### Response Example
```json
{
    "data": {
        "ID": "336cb9f7-3733-4e5a-9ab7-c42a05ebff22",
        "MerchantID": "1e4e6029-2cc9-4b2c-87c1-7a4b2af6d6c6",
        "TransactionID": "0ceec557-418c-476d-a9b2-def89048dc4d",
        "reason": "some reason",
        "internalTransactionID": "121212",
        "token": "card_sandbox_8Aq30HAc8TLFUFvTjqwo556i",
        "ReturnResponse": {
            "status": "PASS",
            "responseCode": "A0000",
            "responseMessage": "Success",
            "authCode": "255385",
            "hostResponseCode": "00",
            "hostReferenceNumber": "497915451651",
            "taskID": "20501784",
            "transactionID": "76968598",
            "transactionTimestamp": "2025-04-02T18:58:21",
            "orderNumber": "59753509",
            "processedAmount": "16.40",
            "externalReferenceID": "59753509",
            "customerReceipt": "        Sandbox US Merchant         \n        200 Epcot Center Dr         \n         Orlando, FL 32836          \n            800-490-8514            \n                 \n                 \n        2025-04-02 06:58 PM         \n               REFUND               \n            Card # 1111             \n          Card Type: VISA           \n         Entry Mode : KEYED         \n      Transaction ID: 76968598      \n        SUBTOTAL: USD $16.40        \n         TOTAL: USD $16.40          \n                 \n                 \n        NO SIGNATURE REQUIRED        \n              APPROVED              \n                 \n                 \n                 \n                 \n                 \n                 \n                 \n                 \n                 \n                 \n           Customer Copy            \n",
            "merchantReceipt": "        Sandbox US Merchant         \n        200 Epcot Center Dr         \n         Orlando, FL 32836          \n            800-490-8514            \n                 \n                 \n        2025-04-02 06:58 PM         \n               REFUND               \n            Card # 1111             \n          Card Type: VISA           \n         Entry Mode : KEYED         \n      Transaction ID: 76968598      \n        SUBTOTAL: USD $16.40        \n         TOTAL: USD $16.40          \n                 \n                 \n      X_______________________      \nI AGREE TO PAY ABOVE TOTAL AMOUNT IN\n ACCORDANCE WITH CARD ISSUER's AGREE\nMENT (MERCHANT AGREEMENT IF CREDIT V\n              OUCHER)               \n     KEEP COPY FOR YOUR RECORDS     \n               \n \n                \n              APPROVED              \n                 \n                 \n                 \n                 \n                 \n                 \n                 \n                 \n                 \n                 \n           Merchant Copy            \n",
            "maskedCardNumber": "1111",
            "cardType": "visa",
            "bank_routing_number":"121122676", 
            "masked_bank_account":"9020", 
            "returnedAmount": "16.40"
        },
        "Metadata": {
            "customerId": "123",
            "email": "test@test.com"
        },
        "order_number": "150t65898",
        "device": {
            "id":"a42627a7-1368-4f2d-b22e-f78f2d216d3e",
            "type":"pax",
            "name":"Shaun's Mobile",
            "model":"S24",
            "serial_number":"1234de30e5fcfcbb7819c18e264ce4000dd0",
            "sdk_version":"1.0.0",
            "manufacturer": "Pax",
            "app_version": "1.0.0 (1)",
            "os": "android",
            "os_version": "14"
        }
    }
}
```
```

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

### Sample Payment Platform API Request (JavaScript)

Source: https://docs.paymentplatform.dev/merchant-api-reference/transactions/credit-card-capture

An example of a JSON request payload for initiating a payment transaction. This includes essential transaction details like amount and description.

```javascript
{
    
    "id": "54191797",
    "data": {
        "transactionAmount": "11.00",
        "description": "Payment for the services"
    }
}
```

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

### Example Error Response: Card Not Found (JSON)

Source: https://docs.paymentplatform.dev/merchant-api-reference/transactions/credit-card-sale

This JSON response signifies that the requested card could not be found in the system. It uses an 'error' flag and provides a specific 'message' for the error.

```json
{
    "error":true,
    "message":"E136 - Card not found"
}
```

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

### Sample Payment Platform API Response (JavaScript)

Source: https://docs.paymentplatform.dev/merchant-api-reference/transactions/credit-card-capture

An example of a JSON response payload after a payment transaction. It contains detailed information about the transaction status, capture details, and associated metadata.

```javascript
{
    "data": {
        "ID": "2a0e8a3b-7703-4d31-a8cd-c714fed4dedf",
        "MerchantID": "1e4e6029-2cc9-4b2c-87c1-7a4b2af6d6c6",
        "TransactionID": "ca8c6e03-1699-4528-bb0c-5894e87ecf47",
        "Description": "Description of transaction",
        "internalTransactionID": "987654321",
        "CaptureResponse": {
            "status": "PASS",
            "responseCode": "A0000",
            "responseMessage": "Success",
            "authCode": "323072",
            "hostResponseCode": "00",
            "hostReferenceNumber": "325806055923",
            "taskID": "95103204",
            "transactionID": "67868150",
            "transactionTimestamp": "2025-04-02T18:26:38",
            "cardType": "visa",
            "transactionAmount": "1.00",
            "processedAmount": "1.00",
            "totalAmount": "1.00",
            "customerReceipt": "        Sandbox US Merchant         \n        200 Epcot Center Dr         \n         Orlando, FL 32836          \n            800-490-8514            \n                 \n                 \n        2025-04-02 06:26 PM         \n           CREDIT - SALE            \n            Card # 1111             \n          Card Type: VISA           \n         Entry Mode : KEYED         \n      Transaction ID: 67868150      \n     Description: Test Capture      \n        SUBTOTAL: USD $1.00         \n          TOTAL: USD $1.00          \n                 \n                 \n        NO SIGNATURE REQUIRED        \n              APPROVED              \n                 \n                 \n                 \n                 \n                 \n                 \n                 \n                 \n                 \n                 \n           Customer Copy            \n",
            "merchantReceipt": "        Sandbox US Merchant         \n        200 Epcot Center Dr         \n         Orlando, FL 32836          \n            800-490-8514            \n                 \n                 \n        2025-04-02 06:26 PM         \n           CREDIT - SALE            \n            Card # 1111             \n          Card Type: VISA           \n         Entry Mode : KEYED         \n      Transaction ID: 67868150      \n     Description: Test Capture      \n        SUBTOTAL: USD $1.00         \n          TOTAL: USD $1.00          \n                 \n                 \n      X_______________________      \nI AGREE TO PAY ABOVE TOTAL AMOUNT IN\n ACCORDANCE WITH CARD ISSUER's AGREE\nMENT (MERCHANT AGREEMENT IF CREDIT V\n              OUCHER)               \n     KEEP COPY FOR YOUR RECORDS     \n               \n \n                \n              APPROVED              \n                 \n                 \n                 \n                 \n                 \n                 \n                 \n                 \n                 \n                 \n           Merchant Copy            \n",
            "maskedCardNumber": "1111"
        },
        "Metadata": {
            "customerId": "123",
            "email": "test@test.com"
        }
    }
}
```

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

### Example Response: 3DS Failed Transaction (JSON)

Source: https://docs.paymentplatform.dev/merchant-api-reference/transactions/credit-card-sale

This JSON response details a transaction where the 3D Secure (3DS) authentication failed. It includes transaction identifiers and a 'ThreeDSStatus' field indicating the failure.

```json
{
   "data": {
        "ID":"cb7010a3-fbfd-4cfc-a1a2-cd6455f2058e",
        "TransactionID":"a4e28094-a243-4dc8-9ba3-63be4023cddd",
        "MerchantID":"90f60f5d-0f35-4125-91aa-3f4532f4bafe",
        "ThreeDSActionRequired":false,
        "ThreeDSStatus":"failed",
        "ThreeDSType":"frictionless",
        "SaleResponse": {
            "status":"FAIL",
            "responseCode":"D",
            "responseMessage":"3DS Directory Server Error" //Other error message could 3DS failed: transStatus`
        }
    }
}
```

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

### Load Platform Library with fetchAccessToken (npm)

Source: https://docs.paymentplatform.dev/merchant-api-reference/secure-fields/secure-fields-overview

Demonstrates how to load the Platform library using npm. It defines an asynchronous function 'fetchAccessToken' that retrieves a Merchant Session Token from a server endpoint and then initializes the Platform library with this function.

```javascript
import { loadPlatform } from "payengine";
import axios from "axios";

const fetchAccessToken = async () => {
    const { data } = await axios.get("/session/token", {
      withCredentials: true,
    });
    return data;
};

const payengineInstance = await loadPlatform({
  fetchAccessToken: fetchAccessToken
});

// Initialize SecureField JS here
```

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

### Load Platform Library with fetchAccessToken

Source: https://docs.paymentplatform.dev/merchant-api-reference/secure-fields/secure-fields-overview

Demonstrates how to load the Platform library and configure it with a function to fetch access tokens, which is necessary for using SecureField JS with OAuth.

```APIDOC
## Load Platform library with OAuth Token

### Description
This section details how to load the Platform library and configure the `fetchAccessToken` function, which is crucial for obtaining Merchant Session Tokens when using OAuth 2.0 authentication.

### Method
Asynchronous function call

### Endpoint
N/A (Client-side JavaScript)

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example (JavaScript - npm)
```javascript
import { loadPlatform } from "payengine";
import axios from "axios";

const fetchAccessToken = async () => {
    const { data } = await axios.get("/session/token", {
      withCredentials: true,
    });
    return data;
};

const payengineInstance = await loadPlatform({
  fetchAccessToken: fetchAccessToken
});

// Initialize SecureField JS here
```

### Request Example (JavaScript - Without npm)
```html
<head>
  <script src="https://<payengine-partner-server>/js/1.0.0/securefields.min.js?onload=scriptLoaded"></script>
  
  <script>
    function scriptLoaded() {
      const fetchAccessToken = async () => {
          const { data } = await axios.get("/session/token", {
            withCredentials: true,
          });
          return data;
      };
      Platform.fetchAccessToken = fetchAccessToken;
      
      // initialize SecureField JS here
    }
  </script>
</head>
```

### Response
#### Success Response (200)
N/A (This is a configuration step, not an API call with a direct response)

#### Response Example
N/A
```
Tokens:
Raw