Accounts Payable

Payment Gateway Agent

API Reference

Mercoa’s payment gateway agent enables you to seamlessly detect and take action on opportunities to convert a non-card payment to card spend from an invoice document.

Agent Actions

Mercoa’s payment gateway agent can perform the following actions:

  • Validate that an invoice contains a card-supporting payment gateway link
  • Process a card payment by running a provided card through the payment gateway

Each action is triggered by the corresponding API endpoint.

Usage

To start using the payment gateway agent, all you need to have is the invoice document or email (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)

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

  • The extracted payment gateway link (if found)
  • Whether the payment gateway supports card
  • 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": "job_1a92b5f7-f522-435e-a953-fd649363730a",
4  "card": {
5    "eligibility": "ACCEPTED",
6    "fee": {
7      "type": "percentage",
8      "value": 2.5
9    }
10  },
11  "paymentGatewayUrl": "https://www.payment-gateway.com/invoice/job_1a92b5f7-f522-435e-a953-fd649363730a",
12  "sessionUrl": "https://www.payment-gateway.com/session/job_1a92b5f7-f522-435e-a953-fd649363730a"
13}

Processing

Once you’ve identified an invoice that supports card spend, you can process the payment triggering a processing job with the invoice document and details of the card to be used for the payment.

POST
/payment-gateway/process
1from mercoa import Mercoa
2from mercoa.payment_gateway_types import (
3    ProcessPaymentGatewayCardDetails_Iframe,
4    ProcessPaymentGatewayRequest_Html,
5)
6
7client = Mercoa(
8    token="YOUR_TOKEN",
9)
10client.payment_gateway.create_process_job(
11    request=ProcessPaymentGatewayRequest_Html(
12        html='<html><body><h1>Invoice Details</h1><a href="https://www.payment-gateway.com/invoice/123123">Pay Invoice</a></body></html>',
13        card_details=ProcessPaymentGatewayCardDetails_Iframe(
14            first_name="John",
15            last_name="Doe",
16            postal_code="12345",
17            country="US",
18            iframe_url="https://www.myvirtualcard.com/iframe/543543",
19        ),
20    ),
21)

We recommend that you provide card details via an iFrame link rather than directly in the request body to avoid exposing sensitive data.

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

  • The receipt URL for the payment
  • A session replay link to review the agent’s actions

If the agent is unable to process the payment, no funds will be moved and the result will contain a descriptive error message explaining what went wrong.

GET
/payment-gateway/process/:jobId
1from mercoa import Mercoa
2
3client = Mercoa(
4    token="YOUR_TOKEN",
5)
6client.payment_gateway.get_process_job(
7    job_id="job_1a92b5f7-f522-435e-a953-fd649363730a",
8)
1{
2  "jobStatus": "success",
3  "jobId": "job_1a92b5f7-f522-435e-a953-fd649363730a",
4  "receiptUrl": "https://www.payment-gateway.com/receipt/123123",
5  "sessionUrl": "https://www.payment-gateway.com/session/job_1a92b5f7-f522-435e-a953-fd649363730a"
6}

Webhooks

Mercoa sends webhook notifications when payment gateway jobs complete. You can configure these webhooks in the Mercoa Developer Portal.

Validation Job Completed

When a payment gateway validation job completes (either successfully or with an error), a webhook with the event type paymentGateway.validation.completed is sent to your configured webhook endpoint.

Webhook Payload:

1{
2  "eventType": "paymentGateway.validation.completed",
3  "jobId": "pgv_8f86116b-3b4d-4ded-99ef-3bc929d8c33c",
4  "data": {
5    "jobStatus": "success",
6    "jobId": "job_1a92b5f7-f522-435e-a953-fd649363730a",
7    "card": {
8      "eligibility": "ACCEPTED",
9      "fee": {
10        "type": "percentage",
11        "value": 2.5
12      }
13    },
14    "paymentGatewayUrl": "https://www.payment-gateway.com/invoice/job_1a92b5f7-f522-435e-a953-fd649363730a",
15    "sessionUrl": "https://www.payment-gateway.com/session/job_1a92b5f7-f522-435e-a953-fd649363730a"
16  }
17}

Processing Job Completed

When a payment gateway 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": "job_1a92b5f7-f522-435e-a953-fd649363730a",
7    "receiptUrl": "https://www.payment-gateway.com/receipt/123123",
8    "sessionUrl": "https://www.payment-gateway.com/session/job_1a92b5f7-f522-435e-a953-fd649363730a"
9  }
10}

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": "job_1a92b5f7-f522-435e-a953-fd649363730a",
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.