Transaction Status

This page provides a comprehensive guide to the status object returned in Localpayment API responses for various transaction types. Understanding these statuses is crucial for tracking the lifecycle of your transactions and handling different scenarios appropriately.

Introduction

The status object is a key component of many API responses related to financial operations. It provides information about the current state of a transaction. Each status is represented by a combination of:

• status (String): A human-readable label describing the status (e.g., "Completed," "Rejected," "Approved").
• code (Integer): A numerical code corresponding to the specific status.
• description (String): A detailed explanation of the status and, in some cases, the reason for the status.

While each operation type has its specific statuses, many fall under these general categories:

• InProgress: The transaction has been initiated but is not yet completed. This often involves asynchronous processing or external approvals.
• Completed: The transaction has been successfully processed.
• Rejected: The transaction could not be completed due to an error. The description field will usually provide more details.
• Cancelled: The transaction was cancelled, either by the user or by the system.

Important Considerations:

• Idempotency: When handling API responses, especially for operations that might be retried, design your system to be idempotent. This means that repeated requests with the same parameters should not result in duplicate transactions or unintended side effects. Use unique identifiers (e.g., request IDs) to track and manage requests.
• Webhooks: Localpayment offers webhooks to notify your system about transaction status changes. Relying solely on querying the API for status updates can be inefficient. Use webhooks to get real-time updates.
• Error Handling: Implement robust error handling to gracefully handle failed transactions and provide informative feedback to users. Log failed transaction details for debugging and analysis.
• Asynchronous Operations: Be aware that many operations, especially those involving external payment processors or banks, are asynchronous. Your system should be able to handle pending statuses and update the transaction status accordingly when it changes.
• Status Changes: Be aware that one transaction can have multiple status. You need to check the transaction history.

The following sections detail the possible status codes for each transaction type.

Payin

Payin transactions represent funds being deposited into a Localpayment account.

Subscriptions

Subscription statuses relate to the overall state of a subscription, not individual payments. Individual payment attempts within a subscription are treated as Payin transactions (see above).

Payout

Payout transactions represent funds being withdrawn from a Localpayment account.

Chargeback

Chargebacks are initiated by the cardholder's bank and represent a reversal of a previous Payin.

Credit

Credit transactions represent operations performed using credit cards.

Currency Exchange

Currency Exchange transactions represent the conversion of funds from one currency to another.

Debit

Debit transactions represent operations performed using debit cards.

Expenses

Expenses track costs associated with operations (e.g., fees).

Recall

Recalls are requests to reverse a payment, typically used in specific payment methods or regions.

Refund

Refunds represent the return of funds to a customer for a specific, previously completed Payin.

Return

A Return typically indicates a payment that was sent but could not be delivered to the recipient. This is distinct from a Refund (initiated by the merchant) or a Chargeback (initiated by the cardholder).

Recurring Fee

Recurring Fees are charges related to subscription or account maintenance.

Wire In

Wire In transactions represent incoming wire transfers.

Wire Out

Wire Out transactions represent outgoing wire transfers.