Get Transaction Status
Use this endpoint to get the current status and details of any transaction.Parameters
Parameters
The unique transaction identifier returned from the
/process/
endpointExample Request
Example Request
Response Examples
Below are some examples of responses for payment and withdrawal transactions.Payment Status Response
Payment Status Response
Withdrawal Status Response
Withdrawal Status Response
Pending OXXO Payment Response
Pending OXXO Payment Response
Status Values Reference
Check the following table to see the different status values that can be returned by the API.Status | Description | Typical Duration | Next Steps |
---|---|---|---|
pending | Transaction awaiting completion | Varies by method | Monitor or wait for webhook |
on_hold | Transaction temporarily held | Manual review | Wait for review completion |
processing | Transaction being processed | Minutes to hours | Monitor for completion |
sent_to_provider | Sent to payment provider | Minutes | Monitor for completion |
success | Transaction successfully completed | N/A | Transaction complete |
paid_full | Payment completed in full | N/A | Transaction complete |
in_transit | Payment in transit to destination | Hours | Monitor for completion |
authorized | Payment authorized (cards only) | N/A | Transaction complete |
canceled | Transaction was cancelled | N/A | No further action |
declined | Payment declined by provider/issuer | N/A | Try different method |
rejected | Transaction was rejected | N/A | Try different method |
failed | Transaction processing failed | N/A | Check error details |
Unknown | Status cannot be determined | N/A | Contact support |
expired | Transaction or authorization expired | N/A | Create new transaction |
Status by Payment Method
Each payment method has a different status progression. Check the following items to see the different status progression for each payment method.Card Payments
Card Payments
Card Payments Status Progression:
pending
→authorized
→success
pending
→declined
pending
→failed
SPEI Transfers
SPEI Transfers
SPEI Transfers Status Progression:
pending
→processing
→success
pending
→failed
Cash Payments (OXXO/SafetyPay)
Cash Payments (OXXO/SafetyPay)
Cash Payments Status Progression:
pending
→success
(when customer pays)pending
→expired
(if not paid by expiration)
Withdrawals
Withdrawals
Withdrawals Status Progression:
pending
→processing
→success
pending
→failed
Response Fields
Below are the fields that are included in the response.Field | Type | Description |
---|---|---|
id | string | Unique transaction identifier |
operation_type | string | "payment" or "withdrawal" |
status | string | Current transaction status |
amount | decimal | Transaction amount |
currency | string | Currency code |
merchant_reference | string | Your reference identifier |
created_at | string | ISO 8601 timestamp of creation |
updated_at | string | ISO 8601 timestamp of last update |
Completion Details fields
When the fieldcompletion_details
is present in the response, it means that the transaction has been completed. Here are the fields that are included in the completion_details
object.
Field | Type | Description |
---|---|---|
completion_details.completed_at | string | Completion timestamp |
completion_details.authorization_code | string | Payment authorization code |
completion_details.reference_number | string | Provider reference number |
Transfer Details Fields
The fieldtransfer_details
is present in the response when the transaction is a withdrawal. Here are the fields that are included in the transfer_details
object.
Field | Type | Description |
---|---|---|
transfer_details.transfer_method | string | Transfer method used |
transfer_details.beneficiary_account | string | Masked beneficiary account |
transfer_details.estimated_completion | string | Estimated completion time |
Implementation Examples
Here are some examples of how to implement the status check in different programming languages.Polling Best Practices
When using polling to retrieve the status of a transaction, you should use the following best practices:Polling Intervals
Use these recommendations to set the polling intervals and timeouts for each transaction type.Transaction Type | Recommended Interval | Maximum Timeout |
---|---|---|
Card payments | 5 seconds | 5 minutes |
SPEI transfers | 30 seconds | 4 hours |
Cash payments | 5 minutes | 72 hours |
Withdrawals | 30 seconds | 4 hours |
Efficient Polling Strategy
Here is an example of an efficient polling strategy.Error Handling
Here are some common errors that you may encounter when checking the status of a transaction.Error Code | Description | Solution |
---|---|---|
transaction_not_found | Transaction ID not found | Verify transaction ID |
invalid_transaction_id | Invalid ID format | Check ID format |
authentication_failed | Invalid API key | Verify credentials |
rate_limit_exceeded | Too many requests | Implement backoff |
Error Response Example
When to Check Status
There are different scenarios when you should check the status of a transaction. See details below for some recommendations.Immediate Status Check
Immediate Status Check
- After receiving an HTTP 202 (Accepted) response
- When
next_action
is present in the response - For transactions that require additional steps
Periodic Status Check
Periodic Status Check
- For pending cash payments (every 5–30 minutes)
- For processing SPEI transfers (every 30–60 seconds)
- For withdrawal processing (every 30–60 seconds)
Webhook vs Polling
Webhook vs Polling
- Use webhooks for real-time status updates (recommended)
- Use polling as a backup or when webhooks aren’t available
- Combine both for maximum reliability
Rate Limits
The transaction status endpoint is rate-limited to ensure fair usage and system stability. You can make up to 300 requests per minute to check transaction statuses.Endpoint | Limit | Window |
---|---|---|
GET /transactions// | 300 requests | per minute |
Header | Example Value | Description |
---|---|---|
X-RateLimit-Limit | 300 | Maximum number of requests allowed per window (300) |
X-RateLimit-Remaining | 295 | Number of requests you’ve got left in the current window (295) |
X-RateLimit-Reset | 1640995200 | Unix timestamp for when the rate limit window resets (1640995200) |
Best Practices
Here are some best practices to follow when checking the status of a transaction.Status Monitoring
Status Monitoring
- Use appropriate intervals - Don’t poll too frequently
- Implement exponential backoff - Increase intervals over time
- Set reasonable timeouts - Don’t wait indefinitely
- Handle rate limits - Respect API limits
Error Recovery
Error Recovery
- Retry on network errors - Temporary failures are common
- Log status changes - Track transaction progression
- Alert on stuck transactions - Monitor for unusual delays
- Fallback to support - Escalate unresolved issues
Performance
Performance
- Batch status checks when possible
- Cache recent status to avoid duplicate calls
- Use webhooks instead of polling when available
- Monitor API usage to stay within limits
Next Steps
- Set up Webhooks for real-time status updates
- Review Error Handling for comprehensive error management
- Learn about Payment Methods for method-specific status flows
- Check Production Readiness for monitoring setup