Version: v2

Payment API Error Codes

This page documents all Split Tender–specific error codes for the Payment API (v2). These errors occur when processing payments that involve multiple payment methods. Each error includes the code name, HTTP status, description, recommended developer action, and notes where applicable.

Create Payment API — POST /payments (v2)

Error Codes Summary

Error Title Reference	Error Title	HTTP Status	Detail Message	Scenario	Resolution
Structural Validation Errors	BAD_REQUEST	`400 BAD REQUEST`	paymentAllocations object is missing	paymentAllocations omitted from request	Include a valid paymentAllocations array with one or two entries
Structural Validation Errors	BAD_REQUEST	`400 BAD REQUEST`	More than two payment allocations were provided	More than two allocations provided	Limit paymentAllocations to a maximum of two
Amount Validation Errors	BAD_REQUEST	`400 BAD REQUEST`	payment.amount is outside the valid range (1–99,999,999) or contains decimals	Invalid or decimal total amount	Provide a whole number amount within the allowed range
Amount Validation Errors	BAD_REQUEST	`400 BAD REQUEST`	Allocation amount is outside the valid range or contains decimals	Invalid or decimal allocation amount	Ensure each allocation amount is a whole number between 1–99,999,999
Amount Validation Errors	BAD_REQUEST	`400 BAD REQUEST`	The payment.amount field is missing	Missing total amount	Add a valid payment.amount value
Amount Validation Errors	BAD_REQUEST	`400 BAD REQUEST`	An allocation entry does not contain an amount	Missing allocation amount	Add amount to each paymentAllocations[i]
Amount Validation Errors	BAD_REQUEST	`400 BAD REQUEST`	The sum of all allocation amounts does not equal payment.amount	Allocation sum mismatch	Ensure all allocation amounts add up exactly to the total payment amount
Payment Method Validation Errors	BAD_REQUEST	`400 BAD REQUEST`	Multiple allocations use the same paymentMethodId	Duplicate paymentMethodId across allocations	Use unique payment methods for each allocation
Payment Method Validation Errors	BAD_REQUEST	`400 BAD REQUEST`	Allocation is missing a paymentMethodId	Missing paymentMethodId	Add paymentMethodId for each allocation
Payment Method Validation Errors	BAD_REQUEST	`400 BAD REQUEST`	Provided paymentMethodId is not a valid UUID	Invalid paymentMethodId format	Use a properly formatted UUID string
Partial Authorization	BAD_REQUEST	`400 BAD REQUEST`	partialAuthorization=true, but authorizeCard=false while a card is present	Partial authorization requested without card authorization enabled	Do not use partial authorization unless card authorization is enabled
Retry Limit Error	FORBIDDEN	`403 FORBIDDEN`	Payment retried more than five times with the same merchantTransactionId	Retry limit exceeded	Use a new merchantTransactionId or stop retrying

Error Codes Details

Structural Validation Errors

MISSING_PAYMENT_ALLOCATIONS

Details

paymentAllocations object is missing

HTTP Status: 400

Description: The paymentAllocations object is missing.

Resolution: Include a valid paymentAllocations array with one or two entries.

Request example

{
  "amount": 1,
  "merchantTransactionId": "mtx-missing-allocations",
  "authorizeCard": false,
  "partialAuthorization": false
}

Response example

{
  "title": "BAD_REQUEST",
  "status": 400,
  "detail": "paymentAllocations object is missing",
  "errorDetails": null
}

TOO_MANY_ALLOCATIONS

Details

More than two payment allocations were provided

HTTP Status: 400

Description: More than two payment allocations were provided.

Resolution: Limit paymentAllocations to a maximum of two.

Request example

{  
"amount": 3,  
"merchantTransactionId": "mtx-too-many-allocs",  
"authorizeCard": false,  
"partialAuthorization": false,  
"paymentAllocations": [  
{ "paymentMethodId": "b6df8625-cd25-4123-b345-638aa7b5d011", "amount": 1 },  
{ "paymentMethodId": "f5146db5-2a93-4c7b-82d6-5d9fcb77c601", "amount": 1 },  
{ "paymentMethodId": "5da3cd1f-9b0e-4a92-a977-06b4a23d3a19", "amount": 1 }  
]  
}

Response example

{  
  "title": "BAD_REQUEST",  
  "status": 400,  
  "detail": "More than two payment allocations were provided"
}  

Amount Validation Errors

INVALID_PAYMENT_AMOUNT

Details

payment.amount is outside the valid range or contains decimals

HTTP Status: 400

Description: payment.amount is outside the valid range (1–99,999,999) or contains decimals.

Resolution: Provide a whole number amount within the allowed range.

Request example

{
  "amount": 100000000,
  "merchantTransactionId": "mtx-invalid-payment-amount",
  "authorizeCard": false,
  "partialAuthorization": false,
  "paymentAllocations": [
    {
      "paymentMethodId": "b6df8625-cd25-4123-b345-638aa7b5d011",
      "amount": 50000000
    },
    {
      "paymentMethodId": "f5146db5-2a93-4c7b-82d6-5d9fcb77c601",
      "amount": 50000000
    }
  ]
}

Response example

{
  "title": "BAD_REQUEST",
  "status": 400,
  "detail": "payment.amount is outside the valid range (1–99,999,999) or contains decimals"
}  

INVALID_ALLOCATION_AMOUNT

Details

Allocation amount is outside the valid range or contains decimals

HTTP Status: 400

Description: Allocation amount is outside the valid range or contains decimals.

Resolution: Ensure each allocation amount is a whole number between 1–99,999,999.

Request example

{
  "amount": 1.5,
  "merchantTransactionId": "mtx-decimal-total",
  "authorizeCard": false,
  "partialAuthorization": false,
  "paymentAllocations": [
    {
      "paymentMethodId": "b6df8625-cd25-4123-b345-638aa7b5d011",
      "amount": 1
    },
    {
      "paymentMethodId": "f5146db5-2a93-4c7b-82d6-5d9fcb77c601",
      "amount": 0.5
    }
  ]
}

Response example

{
  "title": "BAD_REQUEST",
  "status": 400,
  "detail": "payment.amount is outside the valid range (1–99,999,999) or contains decimals"
}

MISSING_PAYMENT_AMOUNT

Details

The payment.amount field is missing

HTTP Status: 400

Description: The payment.amount field is missing.

Resolution: Add a valid payment.amount value.

Request example

{
  "merchantTransactionId": "mtx-missing-total",
  "authorizeCard": false,
  "partialAuthorization": false,
  "paymentAllocations": [
    {
      "paymentMethodId": "b6df8625-cd25-4123-b345-638aa7b5d011",
      "amount": 1
    }
  ]
}

Response example

{
  "title": "BAD_REQUEST",
  "status": 400,
  "detail": "The payment.amount field is missing"
}

MISSING_ALLOCATION_AMOUNT

Details

An allocation entry does not contain an amount

HTTP Status: 400

Description: An allocation entry does not contain an amount.

Resolution: Add amount to each paymentAllocations[i].

Request example

{
  "amount": 1,
  "merchantTransactionId": "mtx-missing-allocation-amount",
  "authorizeCard": false,
  "partialAuthorization": false,
  "paymentAllocations": [
    {
      "paymentMethodId": "b6df8625-cd25-4123-b345-638aa7b5d011"
    }
  ]
}

Response example

{
  "title": "BAD_REQUEST",
  "status": 400,
  "detail": "An allocation entry does not contain an amount"
}

ALLOCATION_SUM_MISMATCH

Details

The sum of all allocation amounts does not equal payment.amount

HTTP Status: 400

Description: The sum of all allocation amounts does not equal payment.amount.

Resolution: Ensure all allocation amounts add up exactly to the total payment amount.

Request example

{
  "amount": 10,
  "merchantTransactionId": "mtx-sum-mismatch",
  "authorizeCard": false,
  "partialAuthorization": false,
  "paymentAllocations": [
    {
      "paymentMethodId": "b6df8625-cd25-4123-b345-638aa7b5d011",
      "amount": 4
    },
    {
      "paymentMethodId": "f5146db5-2a93-4c7b-82d6-5d9fcb77c601",
      "amount": 5
    }
  ]
}

Response example

{
  "title": "BAD_REQUEST",
  "status": 400,
  "detail": "The sum of all allocation amounts does not equal payment.amount",
  "errorDetails": null
}

Payment Method Validation Errors

DUPLICATE_PAYMENT_METHOD_ID

Details

Multiple allocations use the same paymentMethodId

HTTP Status: 400

Description: Multiple allocations use the same paymentMethodId.

Resolution: Use unique payment methods for each allocation.

Request example

{
  "amount": 2,
  "merchantTransactionId": "mtx-sum-mismatch",
  "authorizeCard": false,
  "partialAuthorization": false,
  "paymentAllocations": [
    {
      "paymentMethodId": "b6df8625-cd25-4123-b345-638aa7b5d011",
      "amount": 1
    },
    {
      "paymentMethodId": "b6df8625-cd25-4123-b345-638aa7b5d011",
      "amount": 1
    }
  ]
}

Response example

{
  "title": "BAD_REQUEST",
  "status": 400,
  "detail": "Multiple allocations use the same paymentMethodId"
}

MISSING_PAYMENT_METHOD_ID

Details

Allocation is missing a paymentMethodId

HTTP Status: 400

Description: Allocation is missing a paymentMethodId.

Resolution: Add paymentMethodId for each allocation.

Request example

 {
  "amount": 1,
  "merchantTransactionId": "mtx-missing-pmid",
  "authorizeCard": false,
  "partialAuthorization": false,
  "paymentAllocations": [
    {
      "amount": 1
    }
  ]
}

Response example

{
  "title": "BAD_REQUEST",
  "status": 400,
  "detail": "Allocation is missing a paymentMethodId"
}

INVALID_PAYMENT_METHOD_ID

Details

Provided paymentMethodId is not a valid UUID

HTTP Status: 400

Description: Provided paymentMethodId is not a valid UUID.

Resolution: Use a properly formatted UUID string.

Request example

{
  "amount": 1,
  "merchantTransactionId": "mtx-invalid-pmid",
  "authorizeCard": false,
  "partialAuthorization": false,
  "paymentAllocations": [
    {
      "paymentMethodId": "not-a-uuid",
      "amount": 1
    }
  ]
}

Response example

{
  "title": "BAD_REQUEST",
  "status": 400,
  "detail": "Provided paymentMethodId is not a valid UUID"
}

Partial Authorization

PARTIAL_AUTH_NOT_ALLOWED

Details

Partial authorization not allowed unless card authorization is enabled

HTTP Status: 400

Description: Request included partialAuthorization=true, but authorizeCard=false while a card is present.

Resolution: Do not use partial authorization unless card authorization is enabled.

Request example

{
  "amount": 1,
  "merchantTransactionId": "mtx-partial-auth-not-allowed",
  "authorizeCard": false,
  "partialAuthorization": true,
  "paymentAllocations": [
    {
      "paymentMethodId": "b6df8625-cd25-4123-b345-638aa7b5d011",
      "amount": 1
    }
  ]
}

Response example

{
  "title": "BAD_REQUEST",
  "status": 400,
  "detail": "Request included partialAuthorization=true, but authorizeCard=false while a card is present"
}

Retry Limit Error

MAX_PAYMENT_RETRIES_EXCEEDED

Details

Payment retried more than five times with the same merchantTransactionId

HTTP Status: 403

Description: Payment retried more than five times with the same merchantTransactionId.

Resolution: Use a new merchantTransactionId or stop retrying.

Request example

 {
  "amount": 1,
  "merchantTransactionId": "mtx-retry-12345",
  "authorizeCard": false,
  "partialAuthorization": false,
  "paymentAllocations": [
    {
      "paymentMethodId": "b6df8625-cd25-4123-b345-638aa7b5d011",
      "amount": 1
    }
  ]
}

Response example

{
  "title": "FORBIDDEN",
  "status": 403,
  "detail": "Payment retried more than five times with the same merchantTransactionId"
}

Get Payments API

Error Codes Summary

Error Title Reference	Error Title	HTTP Status	Detail Message	Scenario	Resolution
Structural Validation Errors	NOT_FOUND	`404 NOT FOUND`	paymentId is not found in ccg database or paymentId is present in ccg and not associated to the merchant requested	paymentId sent in request	Use a valid paymentId that exists in CCG for the current environment. Verify you’re using the id returned by the Create Payment response; if unavailable, create a new payment to obtain a valid paymentId.
Structural Validation Errors	BAD_REQUEST	`400 BAD REQUEST`	MerchantTransactionId is missing	MerchantTransactionId is not present in request	Add a merchantTransactionId field to the request

Error Codes Details

Structural Validation Errors For Get Payments

Payment Not Found

PAYMENT_NOT_FOUND

Details

Payment not found

HTTP Status: 404

Description: GET /payments/paymentId attempted to retrieve a payment that does not exist in CCG or is not associated with the requesting merchant.

Resolution: Use a valid paymentId returned by the Create Payment response in the same environment, and ensure it belongs to the requesting merchant (MID). If the id is incorrect or belongs to another merchant, retry with the correct merchant credentials or create a new payment to obtain a valid paymentId.

Request example

{
  "method": "GET",
  "path": "/payments/49dd8625-cd25-4123-b345-638aa7b5d011"
}

Response example

{
  "title": "NOT_FOUND",
  "status": 404,
  "detail": "Payment information not found."
}

MerchantTransactionId Missing

MISSING_MERCHANT_TRANSACTION_ID

Details

MerchantTransactionId is missing

HTTP Status: 400

Description: GET /payments/?merchantTransactionId= was requested without the required merchantTransactionId query parameter.

Resolution: Add the merchantTransactionId query parameter to the request URL. Use the exact name merchantTransactionId and provide a non-empty value that corresponds to the transaction you intend to retrieve.

Request example

{
  "method": "GET",
  "path": "get/payments/?merchantTransactionId="
}

Response example

{
  "title": "BAD_REQUEST",
  "status": 400,
  "detail": "Required query parameter 'merchantTransactionId' is not present. Please review API specs https://docs.healthsafepay.com/api-reference/"
}

Cancel Payments API

Error Codes Summary

Error Title Reference	Error Title	HTTP Status	Detail Message	Scenario	Resolution
Structural Validation Errors	NOT_FOUND	`400 BAD REQUEST`	paymentCancellationReason' is missing or null	paymentCancellationReason is required field	provide a paymentCancellationReason that matches one of the allowed enums
Structural Validation Errors	BAD_REQUEST	`400 BAD REQUEST`	Invalid paymentCancellationReason	PaymentCancellationReason should accept only allowed enums	Use one of the allowed enum values exactly as documented (including correct casing)

Error Codes Details

Structural Validation Errors For Cancel Payments

Payment Not Found

MISSING_PAYMENT_CANCELLATION_REASON

Details

PaymentCancellationReason is missing or null

HTTP Status: 400

Description: PATCH /payments/{paymentId}/cancel (v2) was called without the required paymentCancellationReason field, or with paymentCancellationReason set to null. This violates the request contract for canceling a SALE payment.

Resolution: Include paymentCancellationReason in the request body and provide a non-null value that matches one of the allowed enums defined in the API spec. Review the Convenient Checkout API and Split Tender Cancel Business Rules for valid values.

Request example

{
  "method": "PATCH",
  "path": "/payments/49dd8625-cd25-4123-b345-638aa7b5d011/cancel",
  "body": {}
} 

Response example

{
  "title": "BAD_REQUEST",
  "status": 400,
  "detail": "Invalid enum in paymentCancellationReason. paymentCancellationReason should accept only allowed enums"
}

INVALID_PAYMENT_CANCELLATION_REASON

Details

Invalid PaymentCancellationReason

HTTP Status: 400

Description: PATCH /payments/{paymentId}/cancel (v2) included a paymentCancellationReason value that is not in the allowed enumeration for SALE payment cancellations.

Resolution: Use one of the allowed enum values exactly as documented (including correct casing). Refer to the Convenient Checkout API and Split Tender Cancel Business Rules for the list of valid values.

Request example

{
  "method": "PATCH",
  "path": "/payments/49dd8625-cd25-4123-b345-638aa7b5d011/cancel",
  "body": {
    "paymentCancellationReason": "INVALID_REASON"
  }
} 

Response example

{
  "title": "BAD_REQUEST",
  "status": 400,
  "detail": "Invalid enum in paymentCancellationReason. paymentCancellationReason should accept only allowed enums"
}

Create Payment API — POST /payments (v2)​

Error Codes Summary​

Error Codes Details​

Structural Validation Errors​

MISSING_PAYMENT_ALLOCATIONS​

TOO_MANY_ALLOCATIONS​

Amount Validation Errors​

INVALID_PAYMENT_AMOUNT​

INVALID_ALLOCATION_AMOUNT​

MISSING_PAYMENT_AMOUNT​

MISSING_ALLOCATION_AMOUNT​

ALLOCATION_SUM_MISMATCH​

Payment Method Validation Errors​

DUPLICATE_PAYMENT_METHOD_ID​

MISSING_PAYMENT_METHOD_ID​

INVALID_PAYMENT_METHOD_ID​

Partial Authorization​

PARTIAL_AUTH_NOT_ALLOWED​

Retry Limit Error​

MAX_PAYMENT_RETRIES_EXCEEDED​

Get Payments API​

Error Codes Summary​

Error Codes Details​

Structural Validation Errors For Get Payments​

Payment Not Found​

PAYMENT_NOT_FOUND​

MerchantTransactionId Missing​

MISSING_MERCHANT_TRANSACTION_ID​

Cancel Payments API​

Error Codes Summary​

Error Codes Details​

Structural Validation Errors For Cancel Payments​

Payment Not Found​

MISSING_PAYMENT_CANCELLATION_REASON​

INVALID_PAYMENT_CANCELLATION_REASON​

Create Payment API — POST /payments (v2)

Error Codes Summary

Error Codes Details

Structural Validation Errors

MISSING_PAYMENT_ALLOCATIONS

TOO_MANY_ALLOCATIONS

Amount Validation Errors

INVALID_PAYMENT_AMOUNT

INVALID_ALLOCATION_AMOUNT

MISSING_PAYMENT_AMOUNT

MISSING_ALLOCATION_AMOUNT

ALLOCATION_SUM_MISMATCH

Payment Method Validation Errors

DUPLICATE_PAYMENT_METHOD_ID

MISSING_PAYMENT_METHOD_ID

INVALID_PAYMENT_METHOD_ID

Partial Authorization

PARTIAL_AUTH_NOT_ALLOWED

Retry Limit Error

MAX_PAYMENT_RETRIES_EXCEEDED

Get Payments API

Error Codes Summary

Error Codes Details

Structural Validation Errors For Get Payments

Payment Not Found

PAYMENT_NOT_FOUND

MerchantTransactionId Missing

MISSING_MERCHANT_TRANSACTION_ID

Cancel Payments API

Error Codes Summary

Error Codes Details

Structural Validation Errors For Cancel Payments

Payment Not Found

MISSING_PAYMENT_CANCELLATION_REASON

INVALID_PAYMENT_CANCELLATION_REASON