HomeValidate Card Acceptance

Validate Card Acceptance

API Reference

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

You can view the details of the Validation jobs in the admin dashboard.

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.validate.create(
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  "type": "document",
3  "document": "https://example.com/invoice.pdf"
4}

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)
GET
/payment-gateway/validate/:jobId
1from mercoa import Mercoa
2
3client = Mercoa(
4    token="YOUR_TOKEN",
5)
6client.payment_gateway.validate.get(
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  "createdAt": "2024-01-01T00:00:00Z",
13  "updatedAt": "2024-01-01T00:00:00Z"
14}

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  "card": {
6    "eligibility": "ACCEPTED",
7    "fee": {
8      "type": "percentage",
9      "value": 250
10    }
11  },
12  "createdAt": "2024-01-01T00:00:00Z",
13  "updatedAt": "2024-01-01T00:00:00Z"
14}

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  "createdAt": "2024-01-01T00:00:00Z",
7  "updatedAt": "2024-01-01T00:00:00Z"
8}

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)
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)
createdAtstringThe timestamp when the job was created
updatedAtstringThe timestamp when the job was last updated
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    "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": "virtualCardAgent.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    "createdAt": "2024-01-01T00:00:00Z",
10    "updatedAt": "2024-01-01T00:00:00Z"
11  }
12}

For more information about webhooks, see our Webhooks documentation.