Virtual Card Agent

Validate Card Acceptance

API Reference

Mercoa’s Virtual Card Agent enables you to seamlessly detect and validate card payment opportunities from invoice documents.

Usage

To start using the Virtual Card Agent for validation, all you need to have is the invoice document (PDF or HTML).

Validation

First, upon receiving an invoice, you can trigger a validation job with the invoice document to determine if a card conversion is possible.

POST
/payment-gateway/validate
1from mercoa import Mercoa
2from mercoa.payment_gateway_types import ValidatePaymentGatewayRequest_Document
3
4client = Mercoa(
5    token="YOUR_TOKEN",
6)
7client.payment_gateway.create_validation_job(
8    request=ValidatePaymentGatewayRequest_Document(
9        document="data:application/pdf;base64,JVBERi0xLjEKJcKlwrHDqwoKMSAwIG9iagogIDw8IC9UeXBlIC9DYXRhbG9nCiAgICAgL1BhZ2VzIDIgMCBSCiAgPj4KZW5kb2JqCgoyIDAgb2JqCiAgPDwgL1R5cGUgL1BhZ2VzCiAgICAgL0tpZHMgWzMgMCBSXQogICAgIC9Db3VudCAxCiAgICAgL01lZGlhQm94IFswIDAgMzAwIDE0NF0KICA+PgplbmRvYmoKCjMgMCBvYmoKICA8PCAgL1R5cGUgL1BhZ2UKICAgICAgL1BhcmVudCAyIDAgUgogICAgICAvUmVzb3VyY2VzCiAgICAgICA8PCAvRm9udAogICAgICAgICAgIDw8IC9GMQogICAgICAgICAgICAgICA8PCAvVHlwZSAvRm9udAogICAgICAgICAgICAgICAgICAvU3VidHlwZSAvVHlwZTEKICAgICAgICAgICAgICAgICAgL0Jhc2VGb250IC9UaW1lcy1Sb21hbgogICAgICAgICAgICAgICA+PgogICAgICAgICAgID4+CiAgICAgICA+PgogICAgICAvQ29udGVudHMgNCAwIFIKICA+PgplbmRvYmoKCjQgMCBvYmoKICA8PCAvTGVuZ3RoIDU1ID4+CnN0cmVhbQogIEJUCiAgICAvRjEgMTggVGYKICAgIDAgMCBUZAogICAgKEhlbGxvIFdvcmxkKSBUagogIEVUCmVuZHN0cmVhbQplbmRvYmoKCnhyZWYKMCA1CjAwMDAwMDAwMDAgNjU1MzUgZiAKMDAwMDAwMDAxOCAwMDAwMCBuIAowMDAwMDAwMDc3IDAwMDAwIG4gCjAwMDAwMDAxNzggMDAwMDAgbiAKMDAwMDAwMDQ1NyAwMDAwMCBuIAp0cmFpbGVyCiAgPDwgIC9Sb290IDEgMCBSCiAgICAgIC9TaXplIDUKICA+PgpzdGFydHhyZWYKNTY1CiUlRU9GCg==",
10    ),
11)

The Virtual Card Agent can validate card acceptance using multiple input formats:

Document (PDF)

1{
2  "type": "document",
3  "document": "data:application/pdf;base64,JVBERi0xLjEKJcKlwrHDqwoKMSAwIG9iagogIDw8IC9UeXBlIC9DYXRhbG9nCiAgICAgL1BhZ2VzIDIgMCBSCiAgPj4KZW5kb2JqCgoyIDAgb2JqCiAgPDwgL1R5cGUgL1BhZ2VzCiAgICAgL0tpZHMgWzMgMCBSXQogICAgIC9Db3VudCAxCiAgICAgL01lZGlhQm94IFswIDAgMzAwIDE0NF0KICA+PgplbmRvYmoKCjMgMCBvYmoKICA8PCAgL1R5cGUgL1BhZ2UKICAgICAgL1BhcmVudCAyIDAgUgogICAgICAvUmVzb3VyY2VzCiAgICAgICA8PCAvRm9udAogICAgICAgICAgIDw8IC9GMQogICAgICAgICAgICAgICA8PCAvVHlwZSAvRm9udAogICAgICAgICAgICAgICAgICAvU3VidHlwZSAvVHlwZTEKICAgICAgICAgICAgICAgICAgL0Jhc2VGb250IC9UaW1lcy1Sb21hbgogICAgICAgICAgICAgICA+PgogICAgICAgICAgID4+CiAgICAgICA+PgogICAgICAvQ29udGVudHMgNCAwIFIKICA+PgplbmRvYmoKCjQgMCBvYmoKICA8PCAvTGVuZ3RoIDU1ID4+CnN0cmVhbQogIEJUCiAgICAvRjEgMTggVGYKICAgIDAgMCBUZAogICAgKEhlbGxvIFdvcmxkKSBUagogIEVUCmVuZHN0cmVhbQplbmRvYmoKCnhyZWYKMCA1CjAwMDAwMDAwMDAgNjU1MzUgZiAKMDAwMDAwMDAxOCAwMDAwMCBuIAowMDAwMDAwMDc3IDAwMDAwIG4gCjAwMDAwMDAxNzggMDAwMDAgbiAKMDAwMDAwMDQ1NyAwMDAwMCBuIAp0cmFpbGVyCiAgPDwgIC9Sb290IDEgMCBSCiAgICAgIC9TaXplIDUKICA+PgpzdGFydHhyZWYKNTY1CiUlRU9GCg=="
4}

PDF URL

1{
2  "invoice": {
3    "type": "document",
4    "document": "https://example.com/invoice.pdf"
5  }
6}

HTML

1{
2  "type": "html",
3  "html": "<html><body><h1>Invoice Details</h1><a href=\"https://www.payment-gateway.com/invoice/job_1a92b5f7-f522-435e-a953-fd649363730a4567890\">Pay Invoice</a></body></html>"
4}

Job Pending State

When you submit a validation request, the job enters a pending state. During this time:

  • The agent analyzes the provided invoice
  • Searches for payment links and vendor information
  • Determines card acceptance and fee structure
  • Processes the validation logic

Upon successful completion, the result of the validation job will contain the following information:

  • Whether the vendor accepts card payments
  • The associated card processing fees (if applicable)
  • A session replay link to review the agent’s actions
GET
/payment-gateway/validate/:jobId
1from mercoa import Mercoa
2
3client = Mercoa(
4    token="YOUR_TOKEN",
5)
6client.payment_gateway.get_validation_job(
7    job_id="job_1a92b5f7-f522-435e-a953-fd649363730a",
8)
1{
2  "jobStatus": "success",
3  "jobId": "pgv_8f86116b-3b4d-4ded-99ef-3bc929d8c33c",
4  "paymentGatewayUrl": "https://www.payment-gateway.com/invoice/pgv_8f86116b-3b4d-4ded-99ef-3bc929d8c33c",
5  "card": {
6    "eligibility": "ACCEPTED",
7    "fee": {
8      "type": "percentage",
9      "value": 250
10    }
11  }
12}

Success Response

1{
2  "jobStatus": "success",
3  "jobId": "pgv_8f86116b-3b4d-4ded-99ef-3bc929d8c33c",
4  "paymentGatewayUrl": "https://www.payment-gateway.com/invoice/pgv_8f86116b-3b4d-4ded-99ef-3bc929d8c33c",
5  "sessionUrl": "https://www.payment-gateway.com/session/pgv_8f86116b-3b4d-4ded-99ef-3bc929d8c33c",
6  "card": {
7    "eligibility": "ACCEPTED",
8    "fee": {
9      "type": "percentage",
10      "value": 250
11    }
12  }
13}

Failure Response

1{
2  "jobStatus": "failed",
3  "jobId": "pgv_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}

Response Fields

FieldTypeDescription
jobStatusstringThe status of the job (success, failed, pending)
jobIdstringThe unique identifier for the validation job
paymentGatewayUrlstringThe payment gateway URL found in the document (if applicable)
sessionUrlstringThe URL of the playback session for the agent
card.eligibilitystringWhether the payment gateway accepts card payments (ACCEPTED, NOT_ACCEPTED, UNKNOWN)
card.fee.typestringThe type of fee (percentage, flat, none)
card.fee.valuenumberThe fee value (in basis points for percentage, major units for flat)
errorTypestringThe type of error that occurred (only present on failure)
errorMessagestringA descriptive error message (only present on failure)

Webhooks

Mercoa sends webhook notifications when Virtual Card Agent validation jobs complete. You can configure these webhooks in the Mercoa Developer Portal.

Validation Job Completed

When a Virtual Card Agent validation job completes (either successfully or with an error), a webhook with the event type virtualCardAgent.validation.completed is sent to your configured webhook endpoint.

Webhook Payload:

1{
2  "eventType": "virtualCardAgent.validation.completed",
3  "jobId": "pgv_8f86116b-3b4d-4ded-99ef-3bc929d8c33c",
4  "data": {
5    "jobStatus": "success",
6    "jobId": "pgv_8f86116b-3b4d-4ded-99ef-3bc929d8c33c",
7    "paymentGatewayUrl": "https://www.payment-gateway.com/invoice/pgv_8f86116b-3b4d-4ded-99ef-3bc929d8c33c",
8    "card": {
9      "eligibility": "ACCEPTED",
10      "fee": {
11        "type": "percentage",
12        "value": 250
13      }
14    }
15  }
16}

Error Handling

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

1{
2  "eventType": "paymentGateway.validation.completed",
3  "jobId": "pgv_8f86116b-3b4d-4ded-99ef-3bc929d8c33c",
4  "data": {
5    "jobStatus": "failed",
6    "jobId": "pgv_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  }
10}

For more information about webhooks, see our Webhooks documentation.