Virtual Card AgentProcess Card Payments

Process Payment

API Reference

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_Direct,
4    ProcessPaymentGatewayRequest_Document,
5)
6
7client = Mercoa(
8    token="YOUR_TOKEN",
9)
10client.payment_gateway.create_process_job(
11    request=ProcessPaymentGatewayRequest_Document(
12        document="data:application/pdf;base64,JVBERi0xLjEKJcKlwrHDqwoKMSAwIG9iagogIDw8IC9UeXBlIC9DYXRhbG9nCiAgICAgL1BhZ2VzIDIgMCBSCiAgPj4KZW5kb2JqCgoyIDAgb2JqCiAgPDwgL1R5cGUgL1BhZ2VzCiAgICAgL0tpZHMgWzMgMCBSXQogICAgIC9Db3VudCAxCiAgICAgL01lZGlhQm94IFswIDAgMzAwIDE0NF0KICA+PgplbmRvYmoKCjMgMCBvYmoKICA8PCAgL1R5cGUgL1BhZ2UKICAgICAgL1BhcmVudCAyIDAgUgogICAgICAvUmVzb3VyY2VzCiAgICAgICA8PCAvRm9udAogICAgICAgICAgIDw8IC9GMQogICAgICAgICAgICAgICA8PCAvVHlwZSAvRm9udAogICAgICAgICAgICAgICAgICAvU3VidHlwZSAvVHlwZTEKICAgICAgICAgICAgICAgICAgL0Jhc2VGb250IC9UaW1lcy1Sb21hbgogICAgICAgICAgICAgICA+PgogICAgICAgICAgID4+CiAgICAgICA+PgogICAgICAvQ29udGVudHMgNCAwIFIKICA+PgplbmRvYmoKCjQgMCBvYmoKICA8PCAvTGVuZ3RoIDU1ID4+CnN0cmVhbQogIEJUCiAgICAvRjEgMTggVGYKICAgIDAgMCBUZAogICAgKEhlbGxvIFdvcmxkKSBUagogIEVUCmVuZHN0cmVhbQplbmRvYmoKCnhyZWYKMCA1CjAwMDAwMDAwMDAgNjU1MzUgZiAKMDAwMDAwMDAxOCAwMDAwMCBuIAowMDAwMDAwMDc3IDAwMDAwIG4gCjAwMDAwMDAxNzggMDAwMDAgbiAKMDAwMDAwMDQ1NyAwMDAwMCBuIAp0cmFpbGVyCiAgPDwgIC9Sb290IDEgMCBSCiAgICAgIC9TaXplIDUKICA+PgpzdGFydHhyZWYKNTY1CiUlRU9GCg==",
13        card_details=ProcessPaymentGatewayCardDetails_Direct(
14            first_name="John",
15            last_name="Doe",
16            card_number="4242424242424242",
17            expiration_month=10,
18            expiration_year=2025,
19            cvv="123",
20            postal_code="12345",
21            country="US",
22        ),
23    ),
24)

Provide Card Details

To provide the virtual card details to the Virtual Card Agent, you need to generate the virtual card with your issuing partner, and then provide the card details to the Virtual Card Agent.

iFrame Card Details

The simplest way to provide the card details is to use an iFrame link. This will allow the Virtual Card Agent to navigate to the iFrame link and view the card details without exposing the card details directly.

The iFrame link should render just the card details and nothing else (card number, expiration date, CVV, etc.), and all authentication should be handled by the iFrame link using url parameters.

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 working on adding support for more issuing partners, and you can request support for your issuing partner by contacting us at support@mercoa.com.

Direct Card Details

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

1{
2  "type": "document",
3  "document": "data:application/pdf;base64,JVBERi0xLjEKJcKlwrHDqwoKMSAwIG9iagogIDw8IC9UeXBlIC9DYXRhbG9nCiAgICAgL1BhZ2VzIDIgMCBSCiAgPj4KZW5kb2JqCgoyIDAgb2JqCiAgPDwgL1R5cGUgL1BhZ2VzCiAgICAgL0tpZHMgWzMgMCBSXQogICAgIC9Db3VudCAxCiAgICAgL01lZGlhQm94IFswIDAgMzAwIDE0NF0KICA+PgplbmRvYmoKCjMgMCBvYmoKICA8PCAgL1R5cGUgL1BhZ2UKICAgICAgL1BhcmVudCAyIDAgUgogICAgICAvUmVzb3VyY2VzCiAgICAgICA8PCAvRm9udAogICAgICAgICAgIDw8IC9GMQogICAgICAgICAgICAgICA8PCAvVHlwZSAvRm9udAogICAgICAgICAgICAgICAgICAvU3VidHlwZSAvVHlwZTEKICAgICAgICAgICAgICAgICAgL0Jhc2VGb250IC9UaW1lcy1Sb21hbgogICAgICAgICAgICAgICA+PgogICAgICAgICAgID4+CiAgICAgICA+PgogICAgICAvQ29udGVudHMgNCAwIFIKICA+PgplbmRvYmoKCjQgMCBvYmoKICA8PCAvTGVuZ3RoIDU1ID4+CnN0cmVhbQogIEJUCiAgICAvRjEgMTggVGYKICAgIDAgMCBUZAogICAgKEhlbGxvIFdvcmxkKSBUagogIEVUCmVuZHN0cmVhbQplbmRvYmoKCnhyZWYKMCA1CjAwMDAwMDAwMDAgNjU1MzUgZiAKMDAwMDAwMDAxOCAwMDAwMCBuIAowMDAwMDAwMDc3IDAwMDAwIG4gCjAwMDAwMDAxNzggMDAwMDAgbiAKMDAwMDAwMDQ1NyAwMDAwMCBuIAp0cmFpbGVyCiAgPDwgIC9Sb290IDEgMCBSCiAgICAgIC9TaXplIDUKICA+PgpzdGFydHhyZWYKNTY1CiUlRU9GCg==",
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}

Job Pending State

During payment processing:

  • The agent navigates to the vendor’s payment portal
  • Enters the provided card information
  • Completes the payment transaction
  • Captures the payment receipt
  • Returns the payment confirmation

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": "pgp_8f86116b-3b4d-4ded-99ef-3bc929d8c33c",
4  "receiptUrl": "https://www.payment-gateway.com/receipt/123123",
5  "sessionUrl": "https://www.payment-gateway.com/session/pgp_8f86116b-3b4d-4ded-99ef-3bc929d8c33c"
6}

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  "sessionUrl": "https://www.payment-gateway.com/session/pgp_8f86116b-3b4d-4ded-99ef-3bc929d8c33c"
6}

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}

Response Fields

FieldTypeDescription
jobStatusstringThe status of the job (success, failed, pending)
jobIdstringThe unique identifier for the processing job
receiptUrlstringThe URL of the receipt that was downloaded from the payment gateway
sessionUrlstringThe URL of the playback session for the agent that processed the payment
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 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    "sessionUrl": "https://www.payment-gateway.com/session/pgp_8f86116b-3b4d-4ded-99ef-3bc929d8c33c"
9  }
10}

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  }
10}

For more information about webhooks, see our Webhooks documentation.