Merchant Management Service
API Reference
Settlement

The Settlement API allows you to manage batch settlements, view settlement history, and send settlement reports.

Settlement History

Retrieves a paginated list of settlement batches.

GET /api/v2/settlement
Authorization: Bearer {jwt}
Accept: application/json

Parameters

NameInTypeRequiredDescription
AuthorizationheaderstringtrueBearer Token
createdStartquerystring(date)falseFilter by start date
createdEndquerystring(date)falseFilter by end date
batchIdquerystringfalseFilter by batch ID
pageSizequerynumberfalseDefault 10, use -1 to get all
pageNumberquerynumberfalseDefault 1

Response

StatusMeaningDescriptionSchema
200OK (opens in a new tab)SuccessWrapper: Response<T>

Example Response (200)

{
  "msg": "SUCCESS",
  "code": 0,
  "data": {
    "current": 1,
    "total": 50,
    "pages": 5,
    "size": 10,
    "records": [
      {
        "paymentAmt": 15000,
        "profileName": "Daily Settlement",
        "profileMessage": "Settlement completed successfully",
        "refundCount": 2,
        "uuid": "S20230615123456",
        "acquirerMid": "123456789012345",
        "mchName": "Demo Merchant",
        "voidAmt": 1000,
        "batchId": "B001234",
        "createdAt": "2023-06-15T15:30:45Z",
        "currency": "USD",
        "acquirerTid": "10001234",
        "state": 1,
        "acquirerRefNo": "REF123456789",
        "acquirerCode": "00",
        "paymentCount": 15,
        "refundAmt": 2000,
        "updatedAt": "2023-06-15T16:45:12Z",
        "voidCount": 1
      }
    ]
  }
}

Settlement Detail

Retrieves detailed information for a specific settlement batch.

GET /api/v2/settlement/{batchId}
Authorization: Bearer {jwt}
Accept: application/json

Parameters

NameInTypeRequiredDescription
AuthorizationheaderstringtrueBearer Token
batchIdpathstringtrueBatch ID

Response

StatusMeaningDescriptionSchema
200OK (opens in a new tab)SuccessWrapper: Response<T>

Example Response (200)

{
  "msg": "SUCCESS",
  "code": 0,
  "data": {
    "paymentAmt": 15000,
    "profileName": "Daily Settlement",
    "profileMessage": "Settlement completed successfully",
    "refundCount": 2,
    "uuid": "S20230615123456",
    "acquirerMid": "123456789012345",
    "mchName": "Demo Merchant",
    "voidAmt": 1000,
    "batchId": "B001234",
    "transactions": [
      {
        "amount": 5000,
        "transType": "SALE",
        "count": 5,
        "paymentMethod": "VISA"
      },
      {
        "amount": 10000,
        "transType": "SALE",
        "count": 10,
        "paymentMethod": "MASTERCARD"
      },
      {
        "amount": 2000,
        "transType": "REFUND",
        "count": 2,
        "paymentMethod": "VISA"
      }
    ],
    "createdAt": "2023-06-15T15:30:45Z",
    "successTime": "2023-06-15T16:45:12Z",
    "currency": "USD",
    "acquirerTid": "10001234",
    "state": 1,
    "acquirerRefNo": "REF123456789",
    "acquirerCode": "00",
    "paymentCount": 15,
    "refundAmt": 2000,
    "voidCount": 1
  }
}

Process Settlement

Initiates the settlement process for a specified batch.

POST /api/v2/settlement/settle
Content-Type: application/json
Authorization: Bearer {jwt}

Parameters

NameInTypeRequiredDescription
AuthorizationheaderstringtrueBearer Token
batchIdbodystringtrueBatch ID to settle

Request Body Example

{
  "batchId": "B001234"
}

Response

StatusMeaningDescriptionSchema
200OK (opens in a new tab)SuccessWrapper: Response<T>

Example Response (200)

{
  "msg": "SUCCESS",
  "code": 0,
  "data": {
    "id": 12345
  }
}

Send Settlement Report Email

Sends a settlement report to the specified email address.

POST /api/v2/settlement/email
Content-Type: application/json
Authorization: Bearer {jwt}

Parameters

NameInTypeRequiredDescription
AuthorizationheaderstringtrueBearer Token
batchIdsbodystringtrueJSON array of batch IDs
emailbodystringtrueEmail recipient address
mchIdbodystringtrueMerchant ID

Request Body Example

{
  "batchIds": "[{\"batchId\": \"B001234\"}, {\"batchId\": \"B001235\"}]",
  "email": "merchant@example.com",
  "mchId": "M12345"
}

Response

StatusMeaningDescriptionSchema
200OK (opens in a new tab)SuccessWrapper: Response<T>

Example Response (200)

{
  "msg": "SUCCESS",
  "code": 0,
  "data": {
    "id": 12345
  }
}