Yassir Payments Documentation

Error Response Format#

All error responses follow the same structure:

Field	Type	Description
`code`	number	HTTP status code
`status`	string	Always `"failed"` for errors
`message`	string	Human-readable error description
`errors`	string[]	Additional details (e.g., validation constraint messages)

HTTP Status Codes#

Status	Meaning	Action
`200`	Success	Request completed successfully
`201`	Created	Resource created successfully
`400`	Bad Request	Check request parameters and error message
`401`	Unauthorized	Check API credentials
`404`	Not Found	Resource does not exist
`409`	Conflict	Resource already exists or concurrent processing conflict
`500`	Server Error	Retry the request

Authentication Errors#

HTTP	Message	Cause
`400`	Client credentials are missing	No `Authorization` header provided
`400`	Client credentials id is missing	Malformed Basic auth header (missing client ID)
`400`	Client credentials are invalid	Wrong client ID or secret
`400`	Invalid access token	The customer access token is invalid
`400`	Access token has expired	The customer access token has expired, refresh it

Customer Errors#

HTTP	Message	Cause
`400`	Customer already exists	A customer with this phone number is already registered
`400`	Customer not found with id {id}	No customer exists with the given ID
`400`	customer with phone: {phone} is not found	No customer registered with this phone number

Payment Intent Errors#

Create Intent#

HTTP	Message	Cause
`400`	customer with id: {userId} is not found	The `userId` does not match any registered customer
`400`	service with code: {code} not found	The `x-service` header value is not a valid service
`400`	service with code: {code} is not active	The service exists but is disabled
`400`	country with code: {code} not found	The `countryCode` or `actionCountryCode` is invalid
`400`	currency with code: {code} not found	The `actionCurrencyCode` is not supported
`409`	Payment action {actionId} already exists with amount {amount}. Cannot change amount to {newAmount}. Amount is immutable after creation.	Reusing an `actionId` with a different amount

Proceed Payment#

HTTP	Message	Cause
`400`	payment not found with id {paymentId}	The payment ID does not exist
`400`	payment is already done	The payment has already succeeded
`400`	payment was rejected	The payment previously failed
`400`	payment is Processing	The payment is already being processed
`400`	client token user phone does not match transaction customer phone	The `x-client-token` belongs to a different user
`400`	pm {code} is not active in this country and currency	The payment method is not available for this country/currency
`409`	payment is already being processed by another request	Concurrent proceed calls for the same payment

Capture & Release#

HTTP	Message	Cause
`400`	Payment not found with id {paymentId}	The payment ID does not exist
`400`	Payment has already been captured	The payment was already captured
`400`	Payment has already been released	The pre-authorization was already released
`400`	Payment is not in pre-authorized state	The payment must be in `PRE_AUTHORIZED` state (statusCode 13) before capture or release
`400`	Capture amount {amount} exceeds remaining capturable amount {remaining}	Trying to capture more than was pre-authorized
`409`	Payment is already being processed by another request	Concurrent capture/release calls

Refund#

HTTP	Message	Cause
`404`	Transaction not found.	The payment ID does not exist
`400`	Transaction has not been captured yet and cannot be refunded	The payment must be in `SUCCEEDED` state first
`400`	Transaction already fully refunded.	No remaining balance to refund
`400`	Transaction cannot be refunded, not accepted.	The payment is not in a refundable state
`400`	Refund amount exceeds refundable amount. Maximum refundable amount is {amount}.	The refund amount is larger than the remaining balance
`400`	Transaction cannot be refunded after cashback has been applied.	Cashback was already applied to this transaction
`409`	Refund failed — transaction was modified concurrently or refund amount exceeds remaining balance. Please retry.	Concurrent refund calls, retry the request

Payment Method Errors#

HTTP	Message	Cause
`404`	No Payment Method Found	No payment methods are available for the given country/currency
`404`	Service not found	The service from `x-service` header does not exist
`404`	Country not found	The `countryCode` is not valid
`404`	PaymentMethod not found	The payment method ID does not exist

Validation Errors#

When request body validation fails (e.g., missing required fields, invalid types), the API returns a 400 with the constraint violation messages in the errors array:

The errors array contains one entry per failed validation constraint, generated from the request DTO field decorators. Fix all listed errors before retrying.