Get Payment Status

Once money is sent, users can retrieve the payment to check on its status using the id field that is included in the response. The schema of the createPayment and getPayment responses are exactly the same. For Example:

GET https://sandbox-api.veem.com/veem/v1.2/payments/{paymentId}

📘
Headers
Three headers are required to use this endpoint.
Required Headers
Name
Type
Required
Description
Authorization
string
Yes
Bearer token (OAuth 2.0) This header holds the bearer token required to use Veem's public API, and belongs to the owner account. Failure to use a valid bearer token will result in a 404 (Not Found) status code in the response. An example of a valid header value is as follows: Bearer c047594b-082c-4da1-be89-08fe3770f4b3
See Get Access Token section to generate your Bearer token
X-Request-Id
string
Yes
This is a unique string that identifies the current API request, and should follow the UUID format. Reusing this header without changing the value will result in a 409 (Conflict) status code in the response. An example X-request-id is as follows:
48855846-628d-4177-b071-80332a116f0a
Content-Type
string
Yes
The content type of the request. Must be application/json

Name	Type	Required	Description
`Authorization`	`string`	Yes	Bearer token (OAuth 2.0) This header holds the bearer token required to use Veem's public API, and belongs to the owner account. Failure to use a valid bearer token will result in a 404 (Not Found) status code in the response. An example of a valid header value is as follows: `Bearer c047594b-082c-4da1-be89-08fe3770f4b3` See Get Access Token section to generate your Bearer token
`X-Request-Id`	`string`	Yes	This is a unique string that identifies the current API request, and should follow the UUID format. Reusing this header without changing the value will result in a 409 (Conflict) status code in the response. An example X-request-id is as follows: `48855846-628d-4177-b071-80332a116f0a`
`Content-Type`	`string`	Yes	The content type of the request. Must be `application/json`

{
    "requestId": "09dc3f97-9013-4f7e-82ac-2ffb15db8c46",
    "notes": "Invoice test",
    "payee": {
        "email": "angel.solorzanosanchez+payeeaae6b3ca-845c-400d-8d1d-8b5955c87a44@veem.com",
        "countryCode": "NG",
        "phone": "tel:+234-808-232-4446"
    },
    "payeeAmount": {
        "number": 50.00,
        "currency": "USD"
    },
    "status": "Authorized",
    "goodFundsPayment": false,
    "realTimePayment": false,
    "sweepToWalletId": 2053,
    "extraInfo": {
        "customInfo": null
    },
    "id": 462454,
    "invoiceId": 455741,
    "exchangeRate": {
        "fromAmount": 50.00,
        "fromCurrency": "USD",
        "toAmount": 50.00,
        "toCurrency": "USD"
    },
    "feeInformation": {
        "payerInfo": {
            "originalAmount": 50.00,
            "feeAmount": 0.00,
            "totalAmount": 50.00,
            "currency": "USD"
        },
        "payeeInfo": {
            "originalAmount": 50.00,
            "feeAmount": 0.00,
            "totalAmount": 50.00,
            "currency": "USD"
        }
    },
    "timeCreated": "2025-02-28T10:52:15.209-08:00",
    "timeUpdated": "2025-02-28T10:53:04.878-08:00",
    "debitCreditTxn": {
        "debitTxn": {
            "id": 7436935,
            "type": "Debit",
            "status": "Initiated",
            "reversalError": null,
            "error": null,
            "lastInitiatedAt": "2025-02-28T10:52:15.209-08:00",
            "completedAt": "2025-02-28T10:52:15.209-08:00
        },
        "creditTxn": {
            "id": 7436936,
            "type": "Credit",
            "status": "Pending",
            "reversalError": null,
            "error": null,
            "lastInitiatedAt": "2025-02-28T10:52:15.209-08:00",
            "completedAt": "2025-02-28T10:52:15.209-08:00
        },
        "refundTxn": null
    },
    "fastTransfer": false,
    "cancelable": false,
    "payerFundingMethodType": "Wallet",
    "receiverFundingMethodType": "Wallet"
}

A payment's status will update a few times until it's completed. We recommend that you check on the status of a payment every 30 min after it's created.

The following table describes the various payment status values:

Status	Description
Drafted	Payment is in drafted state and requires further updates.
Sent	The payment has been sent to the receiver/payee.
PendingAuth	The payment is in pending authorization by Veem.
Authorized	The payment has been authorized and is ready for processing. The money will be withdrawn from sender's bank.
InProgress	The payment has been initiated and receiver will be receiving money shortly.
Complete	The payment is complete and the receiver should have received the money.
Cancelled	The payment has been cancelled by the sender/payer.
Closed	The payment has been closed by Veem by request from the sender, or receiver, or due to an error with the payment.

Partner Notes:

A partner account can be configured to make this API request on behalf of their customers. This requires internal configuration for the partner account by Veem. Once the internal configuration is enabled, the API request can be made using partner account bearer token.

Debit/Credit Transaction Workflow

The debitCreditTxn object provides details about the debit and credit transactions associated with the payment. Here’s how the workflow operates

Debit Transaction
- The debitTxn object represents the debit transaction initiated from the payer's account.
- Possible statuses: Pending, Ready, OnHold, FeeCharged, Initiated, Rejected, Completed, Applied, Closed, RecallPending, RecallCompleted, Reversed.
- If a reversal is attempted and fails, the reversalError field will contain details.
Credit Transaction
- The creditTxn object represents the credit transaction to the payee's account.
- Possible statuses: Pending, Ready, OnHold, FeeCharged, Initiated, Rejected, Completed, Applied, Closed, RecallPending, RecallCompleted, Reversed.
- If a reversal is attempted and fails, the reversalError field will contain details.
Reversal workflow
- If a payment needs to be reversed, the system will attempt to reverse both the debit and credit transactions.
- The status will transition to RecallPending while the reversal is being processed and RecallCompleted once the reversal is successful.
- Errors during reversal will be captured in the reversalError field for the respective transaction.

The following table describes the various transaction status values:

Status	Description
Ready	A "Ready" status indicates that the credit or debit is ready for processing.
Initiated	The debit or credit is now in processing and submitted to the payment partner to process.
On Hold	This is normally a new entry set by the system and applies for either a Credit or a Debit. Most commonly, it happens when a payment credit or debit is rejected or reversed.
Rejected/Reversed	The Payment has received an error on the credit or debit, which must be investigated accordingly.
Complete	The transaction debit is completed, or The transaction credit is completed and the funds should be delivered.