Skip to main content

Failed Transaction Reprocessing

Merchants and sub-merchants can retry their own failed VAS transactions through either the Pagamio VAS portal or the API.

This is a controlled retry path. It is separate from the normal purchase idempotency flow and is designed to let a genuinely failed transaction be attempted again without allowing the same successful transaction to be processed twice.

Who Can Reprocess​

  • Merchant users
  • Sub-merchant users

Partner, vendor, and admin users cannot use this self-service retry flow.

When To Reprocess​

Use reprocessing only when all of the following are true:

  • the original transaction status is FAILED
  • the customer did not receive the service or value
  • the merchant wants to retry the same transaction rather than start a fresh sale

Do not reprocess a transaction that is already COMPLETED, PENDING, or PROCESSING.

How Duplicate Protection Still Works​

The normal POST /purchase flow uses merchantReference as its idempotency key.

  • If the same merchantReference is submitted again and the earlier transaction already succeeded, the API returns the original result instead of processing a second sale.
  • If the earlier transaction is still PENDING or PROCESSING, the API blocks the duplicate attempt.
  • If the earlier transaction failed, the merchant must use the explicit retry flow described on this page.

The retry flow is still protected:

  • only the merchant or sub-merchant that owns the original transaction can retry it
  • only FAILED transactions can be retried
  • once a failed transaction has been retried, that original record cannot be retried again
  • if the new retry also fails, retry the newest failed transaction in the chain instead of the original one

Reprocess Through The Portal​

In the Pagamio VAS portal, the retry action is available from the Transactions page.

Portal Steps​

  1. Sign in as the merchant or sub-merchant who owns the transaction.
  2. Open the Transactions page.
  3. Locate a transaction with status FAILED.
  4. Expand the transaction row to open the detail panel.
  5. Click Retry Transaction.
  6. Review the pre-filled amount.
  7. Change the amount only if needed.
  8. Click Confirm Retry.
  9. Wait for the transactions list to refresh and review the new transaction result.

What The Portal Does​

  • The original transaction record stays unchanged.
  • The portal submits a new retry request to the API.
  • The retry dialog currently lets the merchant adjust the amount only.
  • A successful submission creates a new transaction record in the history.

Reprocess Through The API​

There are two supported API methods.

Method 1: Call POST /purchase With reprocess: true​

This should be the main method documented for merchants integrating directly with the API.

POST /purchase
Authorization: Bearer <YOUR_BEARER_TOKEN>
Content-Type: application/json
{
  "productCode": "AIR-VOD-001",
  "amount": 30.00,
  "mobileNumber": "+27821234567",
  "paymentMethod": "cash",
  "channelId": "YOUR_CHANNEL_ID",
  "merchantReference": "INV-2026-04-000123",
  "reprocess": true
}

Use this when the merchant already has the original purchase details and wants to submit the retry directly through the purchase flow. When reprocessing, reuse the original merchantReference for that failed transaction.

Method 2: Call POST /transactions/{transactionItemCode}/retry​

This is the secondary method.

POST /transactions/{transactionItemCode}/retry

See the full endpoint reference at Retry Failed Transaction.

Use this when the merchant wants the platform to rebuild the failed purchase from stored transaction history and submit the retry from that record.

Method 2 Flow​

  1. Query POST /transactions and find the failed transaction.
  2. Take the transactionId from that failed transaction record.
  3. Call POST /transactions/{transactionItemCode}/retry using that value.
  4. Optionally override the amount, and keep the original merchantReference.
  5. Review the returned transaction response for the new retry attempt.

Method 2 Example Request​

POST /transactions/bdf82429-9ab5-4f1a-bb9a-e469f4f05f05/retry
Authorization: Bearer <YOUR_BEARER_TOKEN>
Content-Type: application/json
{
  "amount": 30.00,
  "merchantReference": "INV-2026-04-000123"
}

What The API Does Internally For Method 2​

  • Rebuilds the original purchase request from the stored transaction history.
  • Applies only the allowed overrides from the retry request.
  • Marks the request as an explicit reprocess so the normal /purchase idempotency shortcut is bypassed for that intentional retry.
  • Creates a new transaction attempt while preserving the original failed record.

Supported Overrides For Method 2​

When retrying through POST /transactions/{transactionItemCode}/retry, only these fields can be changed:

  • amount
  • merchantReference

All other purchase fields are taken from the original failed transaction.

  1. Confirm the original transaction is really FAILED.
  2. Confirm the customer did not already receive value.
  3. Retry once through the portal or through one of the supported API methods.
  4. Wait for the new transaction result before retrying again.
  5. If the retry fails again, use the latest failed retry record for any further attempt.

Escalation Information​

If a retry fails or is blocked unexpectedly, include the following when escalating to support:

  • merchant name
  • sub-merchant name if applicable
  • original transaction ID
  • latest retry transaction ID if one exists
  • merchant reference
  • transaction date and time
  • product or service purchased
  • error message returned by the portal or API

Last updated: June 2026