Process Payment
API Reference
Once you’ve identified an invoice that supports card payment, you can process the payment by triggering a processing job. This involves submitting the invoice document along with the virtual card details.
You can view the details of the Process jobs in the admin dashboard.
Provide Card Details
To provide virtual card details to the Virtual Card Agent:
- Generate the virtual card through your issuing partner.
- Submit the card details to the Virtual Card Agent using one of the following methods.
iFrame Card Details (Recommended)
The recommended approach is to provide an iFrame link containing the card details or use one of our native integrations. The Virtual Card Agent will access this iFrame to retrieve the card data securely.
- The iFrame should display only the card details (card number, expiration date, CVV).
- All required authentication should be embedded within the iFrame URL as query parameters or session tokens.
- This method avoids direct transmission of sensitive card data and maintains PCI compliance.
Note: Ensure that the iFrame is lightweight, renders quickly, and does not include any additional content beyond the card details.
Native Integrations
Mercoa supports native integrations with the following issuing partners:
We are actively working to expand support for additional issuing partners. To request integration with your preferred partner, contact us at support@mercoa.com.
Direct Card Details
We strongly recommend using an iFrame link or native integration to provide card details. Avoid including card information directly in the request body to reduce exposure of sensitive data.
Job Pending State
While the payment job is in a pending state, the Virtual Card Agent performs the following steps:
- Navigates to the vendor’s payment portal
- Enters the provided card details
- Submits the payment
- Captures the payment receipt
- Returns a payment confirmation
Successful Completion
When the payment is successfully processed, the job result will include:
- A receipt URL of the completed payment
Failure Handling
If the agent is unable to complete the payment:
- No funds are moved.
- The job result will include a descriptive error message explaining the reason for the failure.
Job Completed Webhook
Success Response
Failure Response
Response Fields
Webhooks
Mercoa sends webhook notifications when Virtual Card Agent processing jobs complete. You can configure these webhooks in the Mercoa Developer Portal.
Processing Job Completed
When a Virtual Card Agent processing job completes (either successfully or with an error), a webhook with the event type paymentGateway.process.completed
is sent to your configured webhook endpoint.
Webhook Payload:
Error Handling
If a job fails, the webhook will include error information in the response:
For more information about webhooks, see our Webhooks documentation.