For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
Sign inBook a demo
  • Home
    • Introduction
    • How it Works
    • Integrating your BillPay / AP
      • Overview
      • ACH Fallback
      • Stripe Issuing
      • Lithic
      • Marqeta
  • Validate
    • GETFind Validation Jobs
    • POSTCreate Validation Job
    • GETGet Validation Job
  • Process
    • GETFind Process Jobs
    • POSTCreate Process Job
    • GETGet Process Job
  • Webhooks
    • POSTPayment Gateway Validation Job Completed
    • POSTPayment Gateway Process Job Completed
Logo
Sign inBook a demo
On this page
  • API Reference
  • Provide Card Details
  • iFrame Card Details (Recommended)
  • Native Integrations
  • Direct Card Details
  • Job Pending State
  • Successful Completion
  • Failure Handling
  • Job Completed Webhook
  • Success Response
  • Failure Response
  • Response Fields
  • Webhooks
  • Processing Job Completed
  • Error Handling
HomeProcess Card Payments

Process Payment

Was this page helpful?
Previous

ACH Fallback

Next
Built with

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.

POST
/payment-gateway/process
1curl -X POST https://api.mercoa.com/payment-gateway/process \
2     -H "Authorization: Bearer <token>" \
3     -H "Content-Type: application/json" \
4     -d '{
5  "type": "document",
6  "cardDetails": {
7    "type": "direct",
8    "cardNumber": "4242424242424242",
9    "country": "US",
10    "cvv": "123",
11    "expirationMonth": 10,
12    "expirationYear": 2025,
13    "firstName": "John",
14    "lastName": "Doe",
15    "postalCode": "12345",
16    "achDetails": {
17      "routingNumber": "123456789",
18      "accountNumber": "987654321",
19      "accountName": "John Doe"
20    }
21  },
22  "document": "data:application/pdf;base64,JVBERi0xLjEKJcKlwrHDqwoKMSAwIG9iagogIDw8IC9UeXBlIC9DYXRhbG9nCiAgICAgL1BhZ2VzIDIgMCBSCiAgPj4KZW5kb2JqCgoyIDAgb2JqCiAgPDwgL1R5cGUgL1BhZ2VzCiAgICAgL0tpZHMgWzMgMCBSXQogICAgIC9Db3VudCAxCiAgICAgL01lZGlhQm94IFswIDAgMzAwIDE0NF0KICA+PgplbmRvYmoKCjMgMCBvYmoKICA8PCAgL1R5cGUgL1BhZ2UKICAgICAgL1BhcmVudCAyIDAgUgogICAgICAvUmVzb3VyY2VzCiAgICAgICA8PCAvRm9udAogICAgICAgICAgIDw8IC9GMQogICAgICAgICAgICAgICA8PCAvVHlwZSAvRm9udAogICAgICAgICAgICAgICAgICAvU3VidHlwZSAvVHlwZTEKICAgICAgICAgICAgICAgICAgL0Jhc2VGb250IC9UaW1lcy1Sb21hbgogICAgICAgICAgICAgICA+PgogICAgICAgICAgID4+CiAgICAgICA+PgogICAgICAvQ29udGVudHMgNCAwIFIKICA+PgplbmRvYmoKCjQgMCBvYmoKICA8PCAvTGVuZ3RoIDU1ID4+CnN0cmVhbQogIEJUCiAgICAvRjEgMTggVGYKICAgIDAgMCBUZAogICAgKEhlbGxvIFdvcmxkKSBUagogIEVUCmVuZHN0cmVhbQplbmRvYmoKCnhyZWYKMCA1CjAwMDAwMDAwMDAgNjU1MzUgZiAKMDAwMDAwMDAxOCAwMDAwMCBuIAowMDAwMDAwMDc3IDAwMDAwIG4gCjAwMDAwMDAxNzggMDAwMDAgbiAKMDAwMDAwMDQ1NyAwMDAwMCBuIAp0cmFpbGVyCiAgPDwgIC9Sb290IDEgMCBSCiAgICAgIC9TaXplIDUKICA+PgpzdGFydHhyZWYKNTY1CiUlRU9GCg=="
23}'
Try it

Provide Card Details

To provide virtual card details to the Virtual Card Agent:

  1. Generate the virtual card through your issuing partner.
  2. 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.

1{
2  "type": "html",
3  "html": "<html><body><h1>Invoice Details</h1><a href=\"https://www.payment-gateway.com/invoice/123123\">Pay Invoice</a></body></html>",
4  "cardDetails": {
5    "type": "iframe",
6    "firstName": "John",
7    "lastName": "Doe",
8    "postalCode": "12345",
9    "country": "US",
10    "iframeUrl": "https://www.myvirtualcard.com/iframe/345345"
11  }
12}

Native Integrations

Mercoa supports native integrations with the following issuing partners:

  • Stripe Issuing
  • Lithic
  • Marqeta

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.

1{
2  "type": "document",
3  "document": "data:application/pdf;base64,...",
4  "cardDetails": {
5    "type": "direct",
6    "firstName": "John",
7    "lastName": "Doe",
8    "cardNumber": "4242424242424242",
9    "expirationMonth": 10,
10    "expirationYear": 2025,
11    "cvv": "123",
12    "postalCode": "12345",
13    "country": "US"
14  }
15}

ACH Fallback: To automatically avoid card processing fees, you can configure ACH fallback. See our dedicated ACH Fallback documentation for complete details on setup and configuration.

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.
GET
/payment-gateway/process/:jobId
1curl https://api.mercoa.com/payment-gateway/process/job_1a92b5f7-f522-435e-a953-fd649363730a \
2     -H "Authorization: Bearer <token>"
Try it
1{
2  "jobStatus": "success",
3  "jobId": "pgp_8f86116b-3b4d-4ded-99ef-3bc929d8c33c",
4  "receiptUrl": "https://www.payment-gateway.com/receipt/123123",
5  "attempts": [{
6    "id": "pgpa_8f86116b-3b4d-4ded-99ef-3bc929d8c33c",
7    "status": "COMPLETED",
8    "amount": 150.75,
9    "receiptUrl": "https://www.payment-gateway.com/receipt/123123",
10    "createdAt": "2024-01-01T00:00:00Z"
11  }],
12  "createdAt": "2024-01-01T00:00:00Z",
13  "updatedAt": "2024-01-01T00:00:00Z"
14}

Job Completed Webhook

Success Response

1{
2  "jobStatus": "success",
3  "jobId": "pgp_8f86116b-3b4d-4ded-99ef-3bc929d8c33c",
4  "receiptUrl": "https://www.payment-gateway.com/receipt/123123",
5  "attempts": [{
6    "id": "pgpa_8f86116b-3b4d-4ded-99ef-3bc929d8c33c",
7    "status": "COMPLETED",
8    "amount": 150.75,
9    "receiptUrl": "https://www.payment-gateway.com/receipt/123123",
10    "createdAt": "2024-01-01T00:00:00Z"
11  }],
12  "createdAt": "2024-01-01T00:00:00Z",
13  "updatedAt": "2024-01-01T00:00:00Z"
14}

Failure Response

1{
2  "jobStatus": "failed",
3  "jobId": "pgp_8f86116b-3b4d-4ded-99ef-3bc929d8c33c",
4  "errorType": "NO_VALID_PAYMENT_GATEWAY_FOUND",
5  "errorMessage": "No valid payment gateway was found in the document or HTML",
6  "attempts": [],
7  "createdAt": "2024-01-01T00:00:00Z",
8  "updatedAt": "2024-01-01T00:00:00Z"
9}

Response Fields

FieldTypeDescription
jobStatusstringStatus of the job: success, failed, or pending.
jobIdstringUnique identifier for the processing job.
receiptUrlstringURL of the payment receipt downloaded from the vendor portal.
attemptsarrayList of payment gateway attempts for this job.
createdAtstringThe timestamp when the job was created.
updatedAtstringThe timestamp when the job was last updated.
errorTypestringError code, present only if the job failed.
errorMessagestringHuman-readable explanation of the failure, present only on job failure.

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:

1{
2  "eventType": "paymentGateway.process.completed",
3  "jobId": "pgp_8f86116b-3b4d-4ded-99ef-3bc929d8c33c",
4  "data": {
5    "jobStatus": "success",
6    "jobId": "pgp_8f86116b-3b4d-4ded-99ef-3bc929d8c33c",
7    "receiptUrl": "https://www.payment-gateway.com/receipt/123123",
8    "attempts": [{
9      "id": "pgpa_8f86116b-3b4d-4ded-99ef-3bc929d8c33c",
10      "status": "COMPLETED",
11      "amount": 150.75,
12      "receiptUrl": "https://www.payment-gateway.com/receipt/123123",
13      "createdAt": "2024-01-01T00:00:00Z"
14    }],
15    "createdAt": "2024-01-01T00:00:00Z",
16    "updatedAt": "2024-01-01T00:00:00Z"
17  }
18}

Error Handling

If a job fails, the webhook will include error information in the response:

1{
2  "eventType": "paymentGateway.process.completed",
3  "jobId": "pgp_8f86116b-3b4d-4ded-99ef-3bc929d8c33c",
4  "data": {
5    "jobStatus": "failed",
6    "jobId": "pgp_8f86116b-3b4d-4ded-99ef-3bc929d8c33c",
7    "errorType": "NO_VALID_PAYMENT_GATEWAY_FOUND",
8    "errorMessage": "No valid payment gateway was found in the document or HTML",
9    "createdAt": "2024-01-01T00:00:00Z",
10    "updatedAt": "2024-01-01T00:00:00Z"
11  }
12}

For more information about webhooks, see our Webhooks documentation.