HomeProcess Card Payments

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.

POST
/payment-gateway/process
1from mercoa import Mercoa
2from mercoa.payment_gateway_types import (
3    ProcessPaymentGatewayAchDetails,
4    ProcessPaymentGatewayCardDetails_Direct,
5    ProcessPaymentGatewayRequest_Document,
6)
7
8client = Mercoa(
9    token="YOUR_TOKEN",
10)
11client.payment_gateway.process.create(
12    request=ProcessPaymentGatewayRequest_Document(
13        document="data:application/pdf;base64,JVBERi0xLjEKJcKlwrHDqwoKMSAwIG9iagogIDw8IC9UeXBlIC9DYXRhbG9nCiAgICAgL1BhZ2VzIDIgMCBSCiAgPj4KZW5kb2JqCgoyIDAgb2JqCiAgPDwgL1R5cGUgL1BhZ2VzCiAgICAgL0tpZHMgWzMgMCBSXQogICAgIC9Db3VudCAxCiAgICAgL01lZGlhQm94IFswIDAgMzAwIDE0NF0KICA+PgplbmRvYmoKCjMgMCBvYmoKICA8PCAgL1R5cGUgL1BhZ2UKICAgICAgL1BhcmVudCAyIDAgUgogICAgICAvUmVzb3VyY2VzCiAgICAgICA8PCAvRm9udAogICAgICAgICAgIDw8IC9GMQogICAgICAgICAgICAgICA8PCAvVHlwZSAvRm9udAogICAgICAgICAgICAgICAgICAvU3VidHlwZSAvVHlwZTEKICAgICAgICAgICAgICAgICAgL0Jhc2VGb250IC9UaW1lcy1Sb21hbgogICAgICAgICAgICAgICA+PgogICAgICAgICAgID4+CiAgICAgICA+PgogICAgICAvQ29udGVudHMgNCAwIFIKICA+PgplbmRvYmoKCjQgMCBvYmoKICA8PCAvTGVuZ3RoIDU1ID4+CnN0cmVhbQogIEJUCiAgICAvRjEgMTggVGYKICAgIDAgMCBUZAogICAgKEhlbGxvIFdvcmxkKSBUagogIEVUCmVuZHN0cmVhbQplbmRvYmoKCnhyZWYKMCA1CjAwMDAwMDAwMDAgNjU1MzUgZiAKMDAwMDAwMDAxOCAwMDAwMCBuIAowMDAwMDAwMDc3IDAwMDAwIG4gCjAwMDAwMDAxNzggMDAwMDAgbiAKMDAwMDAwMDQ1NyAwMDAwMCBuIAp0cmFpbGVyCiAgPDwgIC9Sb290IDEgMCBSCiAgICAgIC9TaXplIDUKICA+PgpzdGFydHhyZWYKNTY1CiUlRU9GCg==",
14        card_details=ProcessPaymentGatewayCardDetails_Direct(
15            first_name="John",
16            last_name="Doe",
17            card_number="4242424242424242",
18            expiration_month=10,
19            expiration_year=2025,
20            cvv="123",
21            postal_code="12345",
22            country="US",
23            ach_details=ProcessPaymentGatewayAchDetails(
24                routing_number="123456789",
25                account_number="987654321",
26                account_name="John Doe",
27            ),
28        ),
29    ),
30)

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.

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:

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
1from mercoa import Mercoa
2
3client = Mercoa(
4    token="YOUR_TOKEN",
5)
6client.payment_gateway.process.get(
7    job_id="job_1a92b5f7-f522-435e-a953-fd649363730a",
8)
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.