Authorize a payment

Dime API Documentation - Payments (1.0.0)

API endpoints for processing payments in the Dime payment system.

Download OpenAPI description
openapi.json
openapi.yaml
Languages
Servers
Mock server
https://docs.dimepay.net/_mock/openapi/
Production server
https://api.dimepay.app/dapi/v1/
Sandbox server for testing
https://sandbox.api.dimepay.app/dapi/v1/

Create a hosted payment page

Request

Headers
client_keystringrequired
Example: abcd1234
Bodyapplication/jsonrequired
langstringrequired

The language that should be used

Example: "en"
datastringrequired

A signed JWT containing the payment input details. Fields to include in the JWT payload:

  • currency: Currency of the payment.
  • id: Unique payment identifier.
  • subtotal: Subtotal of the payment.
  • total: Total amount of the payment.
  • email: Customer's email.
  • tax: Tax applied to the payment.
  • ipAddress: IP address of the customer.
  • fulfillmentStatus: Order's fulfillment status.
  • orderComments: Any comments about the payment.
  • discount: Discount applied to the payment.
  • items: Array of items in the payment.
  • billingPerson: Billing address details.
  • shippingPerson: Shipping address details.
  • referenceTransactionId: Reference to a transaction ID.
  • taxes: Array of tax details.

Example of unsigned payload:

{
  "currency": "USD",
  "id": "XJ12H",
  "subtotal": 1076.64,
  "total": 2014.97,
  "email": "mscott@gmail.com",
  "tax": 488.48,
  "ipAddress": "195.151.247.241",
  "fulfillmentStatus": "AWAITING_PROCESSING",
  "orderComments": "555",
  "discount": 4,
  "items": [
    {
      "id": "xxxx-xxxx-xxxx-xxxx",
      "price": 1060,
      "sku": "ABCA-IAC",
      "quantity": 1,
      "shortDescription": "",
      "name": "iMac",
      "imageUrl": "https://example.com/images/xxxxxx.jpg",
      "selectedOptions": [
        {
          "name": "Color",
          "value": "red",
          "type": "CHOICE"
        }
      ]
    }
  ],
  "billingPerson": {
    "name": "Michael Scott",
    "companyName": "",
    "street": "555 Lackawanna Ave",
    "city": "Scranton",
    "countryCode": "US",
    "countryName": "United States",
    "postalCode": "18508",
    "stateOrProvinceCode": "PA",
    "stateOrProvinceName": "Pennsylvania",
    "phone": ""
  },
  "shippingPerson": {
    "name": "Michael Scott",
    "companyName": "",
    "street": "555 Lackawanna Ave",
    "city": "Scranton",
    "countryCode": "US",
    "countryName": "United States",
    "postalCode": "18508",
    "stateOrProvinceCode": "PA",
    "stateOrProvinceName": "Pennsylvania",
    "phone": ""
  },
  "referenceTransactionId": "transaction_65306446",
  "taxes": [
    {
      "name": "New Tax 2",
      "value": 12,
      "total": 57.1
    }
  ]
}

Example of signing the payload:

const jwt = require('jsonwebtoken');
const payload = { /* fields above */ };
const signedData = jwt.sign(payload, 'your_secret_key');

Final request payload:

{
  "lang": "en",
  "data": "<signed_jwt_token>"
}
Example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
curl -i -X POST \
  https://docs.dimepay.net/_mock/openapi/payments/hosted-page \
  -H 'Content-Type: application/json' \
  -H 'client_key: YOUR_API_KEY_HERE' \
  -d '{
    "lang": "en",
    "data": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }'

Responses

Hosted payment page created successfully

Bodyapplication/json
order_urlstring

URL of the created order

Example: "https://sandbox.dimepay.app/e-order/abcd1234"
Response
application/json
{
  "order_url": "https://sandbox.dimepay.app/e-order/abcd1234"
}

Authorize a payment

Request

Headers
client_keystringrequired
Example: abcd1234
Bodyapplication/jsonrequired
langstringrequired
Example: "en"
datastringrequired

A signed JWT containing the payment input details. Fields to include in the JWT payload:

  • currency: Currency of the payment.
  • id: Unique payment identifier.
  • subtotal: Subtotal of the payment.
  • total: Total amount of the payment.
  • email: Customer's email.
  • tax: Tax applied to the payment.
  • ipAddress: IP address of the customer.
  • fulfillmentStatus: Order's fulfillment status.
  • orderComments: Any comments about the payment.
  • discount: Discount applied to the payment.
  • items: Array of items in the payment.
  • billingPerson: Billing address details.
  • shippingPerson: Shipping address details.
  • referenceTransactionId: Reference to a transaction ID.
  • taxes: Array of tax details.
  • paymentParams: Details of the payment source. Fields:
    • source: Source of the payment (e.g., 'TOKEN').
    • token: Unique token representing the payment method.

Example of unsigned payload:

{
  "currency": "USD",
  "id": "XJ12H",
  "subtotal": 1076.64,
  "total": 2014.97,
  "email": "mscott@gmail.com",
  "tax": 488.48,
  "ipAddress": "195.151.247.241",
  "fulfillmentStatus": "AWAITING_PROCESSING",
  "orderComments": "555",
  "discount": 4,
  "items": [
    {
      "id": "xxxx-xxxx-xxxx-xxxx",
      "price": 1060,
      "sku": "ABCA-IAC",
      "quantity": 1,
      "shortDescription": "",
      "name": "iMac",
      "imageUrl": "https://example.com/images/xxxxxx.jpg",
      "selectedOptions": [
        {
          "name": "Color",
          "value": "red",
          "type": "CHOICE"
        }
      ]
    }
  ],
  "billingPerson": {
    "name": "Michael Scott",
    "companyName": "",
    "street": "555 Lackawanna Ave",
    "city": "Scranton",
    "countryCode": "US",
    "countryName": "United States",
    "postalCode": "18508",
    "stateOrProvinceCode": "PA",
    "stateOrProvinceName": "Pennsylvania",
    "phone": ""
  },
  "shippingPerson": {
    "name": "Michael Scott",
    "companyName": "",
    "street": "555 Lackawanna Ave",
    "city": "Scranton",
    "countryCode": "US",
    "countryName": "United States",
    "postalCode": "18508",
    "stateOrProvinceCode": "PA",
    "stateOrProvinceName": "Pennsylvania",
    "phone": ""
  },
  "referenceTransactionId": "transaction_65306446",
  "taxes": [
    {
      "name": "New Tax 2",
      "value": 12,
      "total": 57.1
    }
  ],
  "paymentParams": {
    "source": "TOKEN",
    "token": "card_PX5n06I5XRue3QX"
  }
}

Example of signing the payload:

const jwt = require('jsonwebtoken');
const payload = { /* fields above */ };
const signedData = jwt.sign(payload, 'your_secret_key');

Final request payload:

{
  "lang": "en",
  "data": "<signed_jwt_token>"
}
Example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
curl -i -X POST \
  https://docs.dimepay.net/_mock/openapi/payments/auth \
  -H 'Content-Type: application/json' \
  -H 'client_key: YOUR_API_KEY_HERE' \
  -d '{
    "lang": "en",
    "data": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }'

Responses

Payment authorized successfully

Bodyapplication/json
idstring(uuid)read-onlyrequired

Primary key, unique ID for the payment

Example: "550e8400-e29b-41d4-a716-446655440000"
amountnumber(double)read-onlyrequired

Amount of the payment

Example: 1200.5
final_amountnumber or null(double)read-only

Final amount after adjustments, if applicable

Example: 1180.5
consumer_feenumber(double)

Fee charged to the consumer

Default 0
Example: 20
currencystringread-onlyrequired

Currency of the payment

Example: "USD"
descriptionstringrequired

Description of the payment

Example: "Payment for Order #12345"
statusstringrequired

Current status of the payment

Enum"COMPLETE""FAILED""PENDING""AUTHORISED""VOID""REFUND"
Example: "COMPLETE"
sourcestringread-onlyrequired

Source of the payment (e.g., CARD, WALLET, POINTS)

Enum"CARD""WALLET""POINTS"
Example: "CARD"
source_accountstring or null(uuid)

UUID of the source account, if applicable

Example: "7db04ed8-cffc-4577-8b50-d3e4c95692aa"
external_transaction_idstring or null

External transaction ID, if available

Example: "EXT123456789"
entity_idstring(uuid)read-onlyrequired

UUID of the entity associated with the payment

Example: "230e8400-e29b-41d4-a716-446655440999"
entity_display_idstring or nullread-only

Display-friendly ID of the entity associated with the payment

Example: "ORD123456"
entity_typestringread-onlyrequired

Type of entity associated with the payment

Enum"TRANSFER""INVOICE""ORDER""BILL"
Example: "ORDER"
customer_idstring or null(uuid)read-only

UUID of the customer associated with the payment, if applicable

Example: "8ec56a2e-2c9e-43a7-8e89-202a2b9497a3"
customerobject or nullread-only

Customer details in JSON format

Example: {"name":"John Doe","email":"johndoe@example.com","phone":"+1234567890"}
brand_idstring or null(uuid)

UUID of the brand associated with the payment, if applicable

Example: "6ff8a7e2-4179-4d3e-9129-920ecb56c412"
payment_method_idstring or null(uuid)

UUID of the payment method used, if available

Example: "4e8ff3b2-35f7-4e87-8a20-1cde38f4592c"
refundedbooleanrequired

Indicates whether the payment has been refunded

Default false
Example: false
settledbooleanrequired

Indicates whether the payment has been settled

Default false
Example: true
source_detailsobject

Details of the payment source in JSON format

Example: {"card_number":"**** **** **** 4242","card_brand":"Visa","card_expiry":"12/25"}
error_codestring or null

Error code if the payment failed

Example: "ERR001"
error_messagestring or null

Error message if the payment failed

Example: "Insufficient funds"
Response
application/json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "amount": 1200.5,
  "final_amount": 1180.5,
  "consumer_fee": 20,
  "currency": "USD",
  "description": "Payment for Order #12345",
  "status": "COMPLETE",
  "source": "CARD",
  "source_account": "7db04ed8-cffc-4577-8b50-d3e4c95692aa",
  "external_transaction_id": "EXT123456789",
  "entity_id": "230e8400-e29b-41d4-a716-446655440999",
  "entity_display_id": "ORD123456",
  "entity_type": "ORDER",
  "customer_id": "8ec56a2e-2c9e-43a7-8e89-202a2b9497a3",
  "customer": {
    "name": "John Doe",
    "email": "johndoe@example.com",
    "phone": "+1234567890"
  },
  "brand_id": "6ff8a7e2-4179-4d3e-9129-920ecb56c412",
  "payment_method_id": "4e8ff3b2-35f7-4e87-8a20-1cde38f4592c",
  "refunded": false,
  "settled": true,
  "source_details": {
    "card_number": "**** **** **** 4242",
    "card_brand": "Visa",
    "card_expiry": "12/25"
  },
  "error_code": "ERR001",
  "error_message": "Insufficient funds"
}

Process a payment sale

Request

Headers
client_keystringrequired
Example: abcd1234
Bodyapplication/jsonrequired
langstringrequired
Example: "en"
datastringrequired

A signed JWT containing the payment input details. Fields to include in the JWT payload:

  • currency: Currency of the payment.
  • id: Unique payment identifier.
  • subtotal: Subtotal of the payment.
  • total: Total amount of the payment.
  • email: Customer's email.
  • tax: Tax applied to the payment.
  • ipAddress: IP address of the customer.
  • fulfillmentStatus: Order's fulfillment status.
  • orderComments: Any comments about the payment.
  • discount: Discount applied to the payment.
  • items: Array of items in the payment.
  • billingPerson: Billing address details.
  • shippingPerson: Shipping address details.
  • referenceTransactionId: Reference to a transaction ID.
  • taxes: Array of tax details.
  • paymentParams: Details of the payment source. Fields:
    • source: Source of the payment (e.g., 'TOKEN').
    • token: Unique token representing the payment method.

Example of unsigned payload:

{
  "currency": "USD",
  "id": "XJ12H",
  "subtotal": 1076.64,
  "total": 2014.97,
  "email": "mscott@gmail.com",
  "tax": 488.48,
  "ipAddress": "195.151.247.241",
  "fulfillmentStatus": "AWAITING_PROCESSING",
  "orderComments": "555",
  "discount": 4,
  "items": [
    {
      "id": "xxxx-xxxx-xxxx-xxxx",
      "price": 1060,
      "sku": "ABCA-IAC",
      "quantity": 1,
      "shortDescription": "",
      "name": "iMac",
      "imageUrl": "https://example.com/images/xxxxxx.jpg",
      "selectedOptions": [
        {
          "name": "Color",
          "value": "red",
          "type": "CHOICE"
        }
      ]
    }
  ],
  "billingPerson": {
    "name": "Michael Scott",
    "companyName": "",
    "street": "555 Lackawanna Ave",
    "city": "Scranton",
    "countryCode": "US",
    "countryName": "United States",
    "postalCode": "18508",
    "stateOrProvinceCode": "PA",
    "stateOrProvinceName": "Pennsylvania",
    "phone": ""
  },
  "shippingPerson": {
    "name": "Michael Scott",
    "companyName": "",
    "street": "555 Lackawanna Ave",
    "city": "Scranton",
    "countryCode": "US",
    "countryName": "United States",
    "postalCode": "18508",
    "stateOrProvinceCode": "PA",
    "stateOrProvinceName": "Pennsylvania",
    "phone": ""
  },
  "referenceTransactionId": "transaction_65306446",
  "taxes": [
    {
      "name": "New Tax 2",
      "value": 12,
      "total": 57.1
    }
  ],
  "paymentParams": {
    "source": "TOKEN",
    "token": "card_PX5n06I5XRue3QX"
  }
}

Example of signing the payload:

const jwt = require('jsonwebtoken');
const payload = { /* fields above */ };
const signedData = jwt.sign(payload, 'your_secret_key');

Final request payload:

{
  "lang": "en",
  "data": "<signed_jwt_token>"
}
Example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
curl -i -X POST \
  https://docs.dimepay.net/_mock/openapi/payments/sale \
  -H 'Content-Type: application/json' \
  -H 'client_key: YOUR_API_KEY_HERE' \
  -d '{
    "lang": "en",
    "data": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }'

Responses

Payment sale processed successfully

Bodyapplication/json
idstring(uuid)read-onlyrequired

Primary key, unique ID for the payment

Example: "550e8400-e29b-41d4-a716-446655440000"
amountnumber(double)read-onlyrequired

Amount of the payment

Example: 1200.5
final_amountnumber or null(double)read-only

Final amount after adjustments, if applicable

Example: 1180.5
consumer_feenumber(double)

Fee charged to the consumer

Default 0
Example: 20
currencystringread-onlyrequired

Currency of the payment

Example: "USD"
descriptionstringrequired

Description of the payment

Example: "Payment for Order #12345"
statusstringrequired

Current status of the payment

Enum"COMPLETE""FAILED""PENDING""AUTHORISED""VOID""REFUND"
Example: "COMPLETE"
sourcestringread-onlyrequired

Source of the payment (e.g., CARD, WALLET, POINTS)

Enum"CARD""WALLET""POINTS"
Example: "CARD"
source_accountstring or null(uuid)

UUID of the source account, if applicable

Example: "7db04ed8-cffc-4577-8b50-d3e4c95692aa"
external_transaction_idstring or null

External transaction ID, if available

Example: "EXT123456789"
entity_idstring(uuid)read-onlyrequired

UUID of the entity associated with the payment

Example: "230e8400-e29b-41d4-a716-446655440999"
entity_display_idstring or nullread-only

Display-friendly ID of the entity associated with the payment

Example: "ORD123456"
entity_typestringread-onlyrequired

Type of entity associated with the payment

Enum"TRANSFER""INVOICE""ORDER""BILL"
Example: "ORDER"
customer_idstring or null(uuid)read-only

UUID of the customer associated with the payment, if applicable

Example: "8ec56a2e-2c9e-43a7-8e89-202a2b9497a3"
customerobject or nullread-only

Customer details in JSON format

Example: {"name":"John Doe","email":"johndoe@example.com","phone":"+1234567890"}
brand_idstring or null(uuid)

UUID of the brand associated with the payment, if applicable

Example: "6ff8a7e2-4179-4d3e-9129-920ecb56c412"
payment_method_idstring or null(uuid)

UUID of the payment method used, if available

Example: "4e8ff3b2-35f7-4e87-8a20-1cde38f4592c"
refundedbooleanrequired

Indicates whether the payment has been refunded

Default false
Example: false
settledbooleanrequired

Indicates whether the payment has been settled

Default false
Example: true
source_detailsobject

Details of the payment source in JSON format

Example: {"card_number":"**** **** **** 4242","card_brand":"Visa","card_expiry":"12/25"}
error_codestring or null

Error code if the payment failed

Example: "ERR001"
error_messagestring or null

Error message if the payment failed

Example: "Insufficient funds"
Response
application/json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "amount": 1200.5,
  "final_amount": 1180.5,
  "consumer_fee": 20,
  "currency": "USD",
  "description": "Payment for Order #12345",
  "status": "COMPLETE",
  "source": "CARD",
  "source_account": "7db04ed8-cffc-4577-8b50-d3e4c95692aa",
  "external_transaction_id": "EXT123456789",
  "entity_id": "230e8400-e29b-41d4-a716-446655440999",
  "entity_display_id": "ORD123456",
  "entity_type": "ORDER",
  "customer_id": "8ec56a2e-2c9e-43a7-8e89-202a2b9497a3",
  "customer": {
    "name": "John Doe",
    "email": "johndoe@example.com",
    "phone": "+1234567890"
  },
  "brand_id": "6ff8a7e2-4179-4d3e-9129-920ecb56c412",
  "payment_method_id": "4e8ff3b2-35f7-4e87-8a20-1cde38f4592c",
  "refunded": false,
  "settled": true,
  "source_details": {
    "card_number": "**** **** **** 4242",
    "card_brand": "Visa",
    "card_expiry": "12/25"
  },
  "error_code": "ERR001",
  "error_message": "Insufficient funds"
}

Capture an authorized payment

Request

Headers
client_keystringrequired
Example: abcd1234
Bodyapplication/jsonrequired
langstringrequired
Example: "en"
datastringrequired

A signed JWT containing the transaction input details. Fields to include in the JWT payload:

  • transaction_id: Unique identifier for the transaction.

Example of unsigned payload:

{
  "transaction_id": "f45bb457-4eb5-40d3-b8df-8915180edfca"
}

Example of signing the payload:

const jwt = require('jsonwebtoken');
const payload = {
  transaction_id: "f45bb457-4eb5-40d3-b8df-8915180edfca"
};
const signedData = jwt.sign(payload, 'your_secret_key');

Final request payload:

{
  "lang": "en",
  "data": "<signed_jwt_token>"
}
Example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
curl -i -X PUT \
  https://docs.dimepay.net/_mock/openapi/payments/capture \
  -H 'Content-Type: application/json' \
  -H 'client_key: YOUR_API_KEY_HERE' \
  -d '{
    "lang": "en",
    "data": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }'

Responses

Payment captured successfully

Bodyapplication/json
idstring(uuid)read-onlyrequired

Primary key, unique ID for the payment

Example: "550e8400-e29b-41d4-a716-446655440000"
amountnumber(double)read-onlyrequired

Amount of the payment

Example: 1200.5
final_amountnumber or null(double)read-only

Final amount after adjustments, if applicable

Example: 1180.5
consumer_feenumber(double)

Fee charged to the consumer

Default 0
Example: 20
currencystringread-onlyrequired

Currency of the payment

Example: "USD"
descriptionstringrequired

Description of the payment

Example: "Payment for Order #12345"
statusstringrequired

Current status of the payment

Enum"COMPLETE""FAILED""PENDING""AUTHORISED""VOID""REFUND"
Example: "COMPLETE"
sourcestringread-onlyrequired

Source of the payment (e.g., CARD, WALLET, POINTS)

Enum"CARD""WALLET""POINTS"
Example: "CARD"
source_accountstring or null(uuid)

UUID of the source account, if applicable

Example: "7db04ed8-cffc-4577-8b50-d3e4c95692aa"
external_transaction_idstring or null

External transaction ID, if available

Example: "EXT123456789"
entity_idstring(uuid)read-onlyrequired

UUID of the entity associated with the payment

Example: "230e8400-e29b-41d4-a716-446655440999"
entity_display_idstring or nullread-only

Display-friendly ID of the entity associated with the payment

Example: "ORD123456"
entity_typestringread-onlyrequired

Type of entity associated with the payment

Enum"TRANSFER""INVOICE""ORDER""BILL"
Example: "ORDER"
customer_idstring or null(uuid)read-only

UUID of the customer associated with the payment, if applicable

Example: "8ec56a2e-2c9e-43a7-8e89-202a2b9497a3"
customerobject or nullread-only

Customer details in JSON format

Example: {"name":"John Doe","email":"johndoe@example.com","phone":"+1234567890"}
brand_idstring or null(uuid)

UUID of the brand associated with the payment, if applicable

Example: "6ff8a7e2-4179-4d3e-9129-920ecb56c412"
payment_method_idstring or null(uuid)

UUID of the payment method used, if available

Example: "4e8ff3b2-35f7-4e87-8a20-1cde38f4592c"
refundedbooleanrequired

Indicates whether the payment has been refunded

Default false
Example: false
settledbooleanrequired

Indicates whether the payment has been settled

Default false
Example: true
source_detailsobject

Details of the payment source in JSON format

Example: {"card_number":"**** **** **** 4242","card_brand":"Visa","card_expiry":"12/25"}
error_codestring or null

Error code if the payment failed

Example: "ERR001"
error_messagestring or null

Error message if the payment failed

Example: "Insufficient funds"
Response
application/json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "amount": 1200.5,
  "final_amount": 1180.5,
  "consumer_fee": 20,
  "currency": "USD",
  "description": "Payment for Order #12345",
  "status": "COMPLETE",
  "source": "CARD",
  "source_account": "7db04ed8-cffc-4577-8b50-d3e4c95692aa",
  "external_transaction_id": "EXT123456789",
  "entity_id": "230e8400-e29b-41d4-a716-446655440999",
  "entity_display_id": "ORD123456",
  "entity_type": "ORDER",
  "customer_id": "8ec56a2e-2c9e-43a7-8e89-202a2b9497a3",
  "customer": {
    "name": "John Doe",
    "email": "johndoe@example.com",
    "phone": "+1234567890"
  },
  "brand_id": "6ff8a7e2-4179-4d3e-9129-920ecb56c412",
  "payment_method_id": "4e8ff3b2-35f7-4e87-8a20-1cde38f4592c",
  "refunded": false,
  "settled": true,
  "source_details": {
    "card_number": "**** **** **** 4242",
    "card_brand": "Visa",
    "card_expiry": "12/25"
  },
  "error_code": "ERR001",
  "error_message": "Insufficient funds"
}

Void a payment

Request

Headers
client_keystringrequired
Example: abcd1234
Bodyapplication/jsonrequired
langstringrequired
Example: "en"
datastringrequired

A signed JWT containing the transaction input details. Fields to include in the JWT payload:

  • transaction_id: Unique identifier for the transaction.

Example of unsigned payload:

{
  "transaction_id": "f45bb457-4eb5-40d3-b8df-8915180edfca"
}

Example of signing the payload:

const jwt = require('jsonwebtoken');
const payload = {
  transaction_id: "f45bb457-4eb5-40d3-b8df-8915180edfca"
};
const signedData = jwt.sign(payload, 'your_secret_key');

Final request payload:

{
  "lang": "en",
  "data": "<signed_jwt_token>"
}
Example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
curl -i -X PUT \
  https://docs.dimepay.net/_mock/openapi/payments/void \
  -H 'Content-Type: application/json' \
  -H 'client_key: YOUR_API_KEY_HERE' \
  -d '{
    "lang": "en",
    "data": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }'

Responses

Payment voided successfully

Bodyapplication/json
idstring(uuid)read-onlyrequired

Primary key, unique ID for the payment

Example: "550e8400-e29b-41d4-a716-446655440000"
amountnumber(double)read-onlyrequired

Amount of the payment

Example: 1200.5
final_amountnumber or null(double)read-only

Final amount after adjustments, if applicable

Example: 1180.5
consumer_feenumber(double)

Fee charged to the consumer

Default 0
Example: 20
currencystringread-onlyrequired

Currency of the payment

Example: "USD"
descriptionstringrequired

Description of the payment

Example: "Payment for Order #12345"
statusstringrequired

Current status of the payment

Enum"COMPLETE""FAILED""PENDING""AUTHORISED""VOID""REFUND"
Example: "COMPLETE"
sourcestringread-onlyrequired

Source of the payment (e.g., CARD, WALLET, POINTS)

Enum"CARD""WALLET""POINTS"
Example: "CARD"
source_accountstring or null(uuid)

UUID of the source account, if applicable

Example: "7db04ed8-cffc-4577-8b50-d3e4c95692aa"
external_transaction_idstring or null

External transaction ID, if available

Example: "EXT123456789"
entity_idstring(uuid)read-onlyrequired

UUID of the entity associated with the payment

Example: "230e8400-e29b-41d4-a716-446655440999"
entity_display_idstring or nullread-only

Display-friendly ID of the entity associated with the payment

Example: "ORD123456"
entity_typestringread-onlyrequired

Type of entity associated with the payment

Enum"TRANSFER""INVOICE""ORDER""BILL"
Example: "ORDER"
customer_idstring or null(uuid)read-only

UUID of the customer associated with the payment, if applicable

Example: "8ec56a2e-2c9e-43a7-8e89-202a2b9497a3"
customerobject or nullread-only

Customer details in JSON format

Example: {"name":"John Doe","email":"johndoe@example.com","phone":"+1234567890"}
brand_idstring or null(uuid)

UUID of the brand associated with the payment, if applicable

Example: "6ff8a7e2-4179-4d3e-9129-920ecb56c412"
payment_method_idstring or null(uuid)

UUID of the payment method used, if available

Example: "4e8ff3b2-35f7-4e87-8a20-1cde38f4592c"
refundedbooleanrequired

Indicates whether the payment has been refunded

Default false
Example: false
settledbooleanrequired

Indicates whether the payment has been settled

Default false
Example: true
source_detailsobject

Details of the payment source in JSON format

Example: {"card_number":"**** **** **** 4242","card_brand":"Visa","card_expiry":"12/25"}
error_codestring or null

Error code if the payment failed

Example: "ERR001"
error_messagestring or null

Error message if the payment failed

Example: "Insufficient funds"
Response
application/json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "amount": 1200.5,
  "final_amount": 1180.5,
  "consumer_fee": 20,
  "currency": "USD",
  "description": "Payment for Order #12345",
  "status": "COMPLETE",
  "source": "CARD",
  "source_account": "7db04ed8-cffc-4577-8b50-d3e4c95692aa",
  "external_transaction_id": "EXT123456789",
  "entity_id": "230e8400-e29b-41d4-a716-446655440999",
  "entity_display_id": "ORD123456",
  "entity_type": "ORDER",
  "customer_id": "8ec56a2e-2c9e-43a7-8e89-202a2b9497a3",
  "customer": {
    "name": "John Doe",
    "email": "johndoe@example.com",
    "phone": "+1234567890"
  },
  "brand_id": "6ff8a7e2-4179-4d3e-9129-920ecb56c412",
  "payment_method_id": "4e8ff3b2-35f7-4e87-8a20-1cde38f4592c",
  "refunded": false,
  "settled": true,
  "source_details": {
    "card_number": "**** **** **** 4242",
    "card_brand": "Visa",
    "card_expiry": "12/25"
  },
  "error_code": "ERR001",
  "error_message": "Insufficient funds"
}

Refund a payment

Request

Headers
client_keystringrequired
Example: abcd1234
Bodyapplication/jsonrequired
langstringrequired
Example: "en"
datastringrequired

A signed JWT containing the transaction input details. Fields to include in the JWT payload:

  • transaction_id: Unique identifier for the transaction.

Example of unsigned payload:

{
  "transaction_id": "f45bb457-4eb5-40d3-b8df-8915180edfca"
}

Example of signing the payload:

const jwt = require('jsonwebtoken');
const payload = {
  transaction_id: "f45bb457-4eb5-40d3-b8df-8915180edfca"
};
const signedData = jwt.sign(payload, 'your_secret_key');

Final request payload:

{
  "lang": "en",
  "data": "<signed_jwt_token>"
}
Example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
curl -i -X PUT \
  https://docs.dimepay.net/_mock/openapi/payments/refund \
  -H 'Content-Type: application/json' \
  -H 'client_key: YOUR_API_KEY_HERE' \
  -d '{
    "lang": "en",
    "data": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }'

Responses

Payment refunded successfully

Bodyapplication/json
idstring(uuid)read-onlyrequired

Primary key, unique ID for the payment

Example: "550e8400-e29b-41d4-a716-446655440000"
amountnumber(double)read-onlyrequired

Amount of the payment

Example: 1200.5
final_amountnumber or null(double)read-only

Final amount after adjustments, if applicable

Example: 1180.5
consumer_feenumber(double)

Fee charged to the consumer

Default 0
Example: 20
currencystringread-onlyrequired

Currency of the payment

Example: "USD"
descriptionstringrequired

Description of the payment

Example: "Payment for Order #12345"
statusstringrequired

Current status of the payment

Enum"COMPLETE""FAILED""PENDING""AUTHORISED""VOID""REFUND"
Example: "COMPLETE"
sourcestringread-onlyrequired

Source of the payment (e.g., CARD, WALLET, POINTS)

Enum"CARD""WALLET""POINTS"
Example: "CARD"
source_accountstring or null(uuid)

UUID of the source account, if applicable

Example: "7db04ed8-cffc-4577-8b50-d3e4c95692aa"
external_transaction_idstring or null

External transaction ID, if available

Example: "EXT123456789"
entity_idstring(uuid)read-onlyrequired

UUID of the entity associated with the payment

Example: "230e8400-e29b-41d4-a716-446655440999"
entity_display_idstring or nullread-only

Display-friendly ID of the entity associated with the payment

Example: "ORD123456"
entity_typestringread-onlyrequired

Type of entity associated with the payment

Enum"TRANSFER""INVOICE""ORDER""BILL"
Example: "ORDER"
customer_idstring or null(uuid)read-only

UUID of the customer associated with the payment, if applicable

Example: "8ec56a2e-2c9e-43a7-8e89-202a2b9497a3"
customerobject or nullread-only

Customer details in JSON format

Example: {"name":"John Doe","email":"johndoe@example.com","phone":"+1234567890"}
brand_idstring or null(uuid)

UUID of the brand associated with the payment, if applicable

Example: "6ff8a7e2-4179-4d3e-9129-920ecb56c412"
payment_method_idstring or null(uuid)

UUID of the payment method used, if available

Example: "4e8ff3b2-35f7-4e87-8a20-1cde38f4592c"
refundedbooleanrequired

Indicates whether the payment has been refunded

Default false
Example: false
settledbooleanrequired

Indicates whether the payment has been settled

Default false
Example: true
source_detailsobject

Details of the payment source in JSON format

Example: {"card_number":"**** **** **** 4242","card_brand":"Visa","card_expiry":"12/25"}
error_codestring or null

Error code if the payment failed

Example: "ERR001"
error_messagestring or null

Error message if the payment failed

Example: "Insufficient funds"
Response
application/json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "amount": 1200.5,
  "final_amount": 1180.5,
  "consumer_fee": 20,
  "currency": "USD",
  "description": "Payment for Order #12345",
  "status": "COMPLETE",
  "source": "CARD",
  "source_account": "7db04ed8-cffc-4577-8b50-d3e4c95692aa",
  "external_transaction_id": "EXT123456789",
  "entity_id": "230e8400-e29b-41d4-a716-446655440999",
  "entity_display_id": "ORD123456",
  "entity_type": "ORDER",
  "customer_id": "8ec56a2e-2c9e-43a7-8e89-202a2b9497a3",
  "customer": {
    "name": "John Doe",
    "email": "johndoe@example.com",
    "phone": "+1234567890"
  },
  "brand_id": "6ff8a7e2-4179-4d3e-9129-920ecb56c412",
  "payment_method_id": "4e8ff3b2-35f7-4e87-8a20-1cde38f4592c",
  "refunded": false,
  "settled": true,
  "source_details": {
    "card_number": "**** **** **** 4242",
    "card_brand": "Visa",
    "card_expiry": "12/25"
  },
  "error_code": "ERR001",
  "error_message": "Insufficient funds"
}