Integrating Mercoa with your BillPay / AP System

Overview

Mercoa’s Virtual Card Agent seamlessly integrates into your existing BillPay / AP workflows to automatically process invoice payments using virtual cards. It’s designed to automatically pay invoices using virtual cards whenever it’s possible and cost-effective. The integration includes a straightforward decision-based flow with a fallback to your current payment system, ensuring no disruption.

Integration Flow

This process is handled in two main phases: validation and processing. Your system first checks if an invoice is eligible for card payment and then acts on that information.

Validation Flow

This chart shows the initial decision-making process.

Processing Flow

If an invoice is cleared for card payment, this is the next step.

Implementation Steps

1. Trigger the Validation

When a payment is scheduled in your system, make a call to the Mercoa Agent’s validation endpoint. This is the entry point to the workflow.

1 // Example: When payment is scheduled
2 async function schedulePayment(invoice) {
3   // Your existing payment scheduling logic
4   const scheduledPayment = await createScheduledPayment(invoice);
5   
6   // Call Mercoa Agent validation
7   const validationResult = await validateWithMercoaAgent(invoice);
8   
9   // Store validation result for later use
10   await storeValidationResult(scheduledPayment.id, validationResult);
11   
12   return scheduledPayment;
13 }

2. Call the Validation Endpoint

Use the Mercoa Agent validation endpoint to check if the vendor’s invoice can be processed with a virtual card.

POST

/payment-gateway/validate

1 curl -X POST https://api.mercoa.com/payment-gateway/validate \
2      -H "Authorization: Bearer <token>" \
3      -H "Content-Type: application/json" \
4      -d '{
5   "type": "document",
6   "document": "data:application/pdf;base64,JVBERi0xLjEKJcKlwrHDqwoKMSAwIG9iagogIDw8IC9UeXBlIC9DYXRhbG9nCiAgICAgL1BhZ2VzIDIgMCBSCiAgPj4KZW5kb2JqCgoyIDAgb2JqCiAgPDwgL1R5cGUgL1BhZ2VzCiAgICAgL0tpZHMgWzMgMCBSXQogICAgIC9Db3VudCAxCiAgICAgL01lZGlhQm94IFswIDAgMzAwIDE0NF0KICA+PgplbmRvYmoKCjMgMCBvYmoKICA8PCAgL1R5cGUgL1BhZ2UKICAgICAgL1BhcmVudCAyIDAgUgogICAgICAvUmVzb3VyY2VzCiAgICAgICA8PCAvRm9udAogICAgICAgICAgIDw8IC9GMQogICAgICAgICAgICAgICA8PCAvVHlwZSAvRm9udAogICAgICAgICAgICAgICAgICAvU3VidHlwZSAvVHlwZTEKICAgICAgICAgICAgICAgICAgL0Jhc2VGb250IC9UaW1lcy1Sb21hbgogICAgICAgICAgICAgICA+PgogICAgICAgICAgID4+CiAgICAgICA+PgogICAgICAvQ29udGVudHMgNCAwIFIKICA+PgplbmRvYmoKCjQgMCBvYmoKICA8PCAvTGVuZ3RoIDU1ID4+CnN0cmVhbQogIEJUCiAgICAvRjEgMTggVGYKICAgIDAgMCBUZAogICAgKEhlbGxvIFdvcmxkKSBUagogIEVUCmVuZHN0cmVhbQplbmRvYmoKCnhyZWYKMCA1CjAwMDAwMDAwMDAgNjU1MzUgZiAKMDAwMDAwMDAxOCAwMDAwMCBuIAowMDAwMDAwMDc3IDAwMDAwIG4gCjAwMDAwMDAxNzggMDAwMDAgbiAKMDAwMDAwMDQ1NyAwMDAwMCBuIAp0cmFpbGVyCiAgPDwgIC9Sb290IDEgMCBSCiAgICAgIC9TaXplIDUKICA+PgpzdGFydHhyZWYKNTY1CiUlRU9GCg=="
7 }'

Try it

JavaScript

Python

Go

Java

1 import { MercoaClient } from "@mercoa/javascript"
2 
3 const mercoa = new MercoaClient({
4   token: "YOUR_API_KEY",
5 })
6 
7 async function validateWithMercoaAgent(invoice) {
8   const validationJob = await mercoa.paymentGateway.createValidationJob({
9     type: "html",
10     html: `<html><body><h1>Invoice ${invoice.id}</h1><p>Amount: $${invoice.amount}</p></body></html>`
11   })
12   
13   return validationJob
14 }

3. Analyze the Validation Response

The validation endpoint returns a response indicating whether the invoice can be paid with a card and lists any applicable fees.

Whether the invoice can be processed with a virtual card
The processing fee (if applicable)
Any additional requirements or restrictions

1 {
2   "canProcessWithCard": true,
3   "processingFee": 2.50,
4   "feeCurrency": "USD",
5   "restrictions": [],
6   "estimatedProcessingTime": "1-2 business days"
7 }

4. Apply Your Decision Logic

Based on the validation response, implement logic on your side to decide the next step.

If card processing isn’t available, fall back to your current workflow.
If it is available, check if the fee is within your acceptable threshold. If not, fall back.
If the fee is acceptable, proceed to process the payment with a virtual card.

JavaScript

Python

Go

Java

1 async function processPaymentDecision(invoice, validationResult) {
2   // If card processing is not available, use current workflow
3   if (validationResult.card?.eligibility !== 'ACCEPTED') {
4     return await processWithCurrentWorkflow(invoice);
5   }
6   
7   // Check if fee is acceptable (implement your threshold logic)
8   const feeThreshold = getFeeThreshold(invoice.amount);
9   const processingFee = validationResult.card?.fee?.value || 0;
10   if (processingFee > feeThreshold) {
11     return await processWithCurrentWorkflow(invoice);
12   }
13   
14   // Proceed with virtual card processing
15   return await processWithVirtualCard(invoice, validationResult);
16 }

5. Process the Payment

If the decision is to use a virtual card, call Mercoa process endpoint. Your implementation should handle both success and failure. If the payment fails for any reason, fall back to your existing workflow.

JavaScript

Python

Go

Java

1 async function processWithVirtualCard(invoice, validationResult) {
2   try {
3     const processJob = await mercoa.paymentGateway.createProcessJob({
4       type: "html",
5       html: `<html><body><h1>Invoice ${invoice.id}</h1><p>Amount: $${invoice.amount}</p></body></html>`,
6       cardDetails: {
7         type: "stripeIssuing",
8         firstName: "John",
9         lastName: "Doe",
10         postalCode: "12345",
11         country: "US",
12         stripeCardId: "ic_1234567890abcdef",
13         stripePublishableKey: "pk_test_1234567890abcdef",
14         ephemeralKeyEndpoint: {
15           url: "https://api.example.com/ephemeral-keys",
16           method: "POST",
17           headers: {
18             "Authorization": "Bearer YOUR_AUTH_SCHEME",
19             "Content-Type": "application/json"
20           },
21           postBody: "{\"card_id\": \"{{cardId}}\", \"nonce\": \"{{nonce}}\", \"account_id\": \"{{accountId}}\"}"
22         }
23       }
24     })
25     
26     if (processJob.jobStatus === 'success') {
27       // Reconcile the payment with your invoice
28       await reconcilePayment(invoice.id, processJob.receiptUrl);
29       return { success: true, method: 'virtual_card' };
30     } else {
31       // Fall back to current workflow
32       return await processWithCurrentWorkflow(invoice);
33     }
34   } catch (error) {
35     // Handle errors and fall back to current workflow
36     console.error('Virtual card processing failed:', error);
37     return await processWithCurrentWorkflow(invoice);
38   }
39 }

6. Reconcile the Payment

When a virtual card payment succeeds, you must reconcile the payment on your side. This typically means updating your invoice’s status to “paid” and storing the transaction details for your records.

JavaScript

Python

Go

Java

1 async function reconcilePayment(invoiceId, receiptUrl) {
2   // Update your invoice status to paid
3   await updateInvoiceStatus(invoiceId, 'paid');
4   
5   // Store transaction details for audit trail
6   await storeTransactionDetails(invoiceId, receiptUrl, {
7     method: 'virtual_card',
8     processedAt: new Date(),
9     // Include other relevant transaction data
10   });
11   
12   // Trigger any post-payment workflows
13   await triggerPostPaymentWorkflows(invoiceId);
14 }

Migration Strategy

We recommend a phased approach to roll out the integration.

Phase 1: Validation Only

Implement the validation endpoint call.
Log the results to analyze vendor eligibility rates and potential fees without actually processing payments.

Phase 2: Limited Processing

Enable virtual card processing for a small, selected group of low-risk vendors or invoices.
Monitor success rates and ensure your reconciliation logic works as expected.

Phase 3: Full Integration

Enable the workflow for all eligible invoices.
Ensure your fallback mechanisms are robust.
Continuously monitor and optimize based on performance data.

Overview

Integration Flow

This process is handled in two main phases: validation and processing. Your system first checks if an invoice is eligible for card payment and then acts on that information.

Validation Flow

This chart shows the initial decision-making process.

Processing Flow

If an invoice is cleared for card payment, this is the next step.

Implementation Steps

1. Trigger the Validation

When a payment is scheduled in your system, make a call to the Mercoa Agent’s validation endpoint. This is the entry point to the workflow.

1 // Example: When payment is scheduled
2 async function schedulePayment(invoice) {
3   // Your existing payment scheduling logic
4   const scheduledPayment = await createScheduledPayment(invoice);
5   
6   // Call Mercoa Agent validation
7   const validationResult = await validateWithMercoaAgent(invoice);
8   
9   // Store validation result for later use
10   await storeValidationResult(scheduledPayment.id, validationResult);
11   
12   return scheduledPayment;
13 }

2. Call the Validation Endpoint

Use the Mercoa Agent validation endpoint to check if the vendor’s invoice can be processed with a virtual card.

POST

/payment-gateway/validate

1 curl -X POST https://api.mercoa.com/payment-gateway/validate \
2      -H "Authorization: Bearer <token>" \
3      -H "Content-Type: application/json" \
4      -d '{
5   "type": "document",
6   "document": "data:application/pdf;base64,JVBERi0xLjEKJcKlwrHDqwoKMSAwIG9iagogIDw8IC9UeXBlIC9DYXRhbG9nCiAgICAgL1BhZ2VzIDIgMCBSCiAgPj4KZW5kb2JqCgoyIDAgb2JqCiAgPDwgL1R5cGUgL1BhZ2VzCiAgICAgL0tpZHMgWzMgMCBSXQogICAgIC9Db3VudCAxCiAgICAgL01lZGlhQm94IFswIDAgMzAwIDE0NF0KICA+PgplbmRvYmoKCjMgMCBvYmoKICA8PCAgL1R5cGUgL1BhZ2UKICAgICAgL1BhcmVudCAyIDAgUgogICAgICAvUmVzb3VyY2VzCiAgICAgICA8PCAvRm9udAogICAgICAgICAgIDw8IC9GMQogICAgICAgICAgICAgICA8PCAvVHlwZSAvRm9udAogICAgICAgICAgICAgICAgICAvU3VidHlwZSAvVHlwZTEKICAgICAgICAgICAgICAgICAgL0Jhc2VGb250IC9UaW1lcy1Sb21hbgogICAgICAgICAgICAgICA+PgogICAgICAgICAgID4+CiAgICAgICA+PgogICAgICAvQ29udGVudHMgNCAwIFIKICA+PgplbmRvYmoKCjQgMCBvYmoKICA8PCAvTGVuZ3RoIDU1ID4+CnN0cmVhbQogIEJUCiAgICAvRjEgMTggVGYKICAgIDAgMCBUZAogICAgKEhlbGxvIFdvcmxkKSBUagogIEVUCmVuZHN0cmVhbQplbmRvYmoKCnhyZWYKMCA1CjAwMDAwMDAwMDAgNjU1MzUgZiAKMDAwMDAwMDAxOCAwMDAwMCBuIAowMDAwMDAwMDc3IDAwMDAwIG4gCjAwMDAwMDAxNzggMDAwMDAgbiAKMDAwMDAwMDQ1NyAwMDAwMCBuIAp0cmFpbGVyCiAgPDwgIC9Sb290IDEgMCBSCiAgICAgIC9TaXplIDUKICA+PgpzdGFydHhyZWYKNTY1CiUlRU9GCg=="
7 }'

Try it

JavaScript

Python

Go

Java

1 import { MercoaClient } from "@mercoa/javascript"
2 
3 const mercoa = new MercoaClient({
4   token: "YOUR_API_KEY",
5 })
6 
7 async function validateWithMercoaAgent(invoice) {
8   const validationJob = await mercoa.paymentGateway.createValidationJob({
9     type: "html",
10     html: `<html><body><h1>Invoice ${invoice.id}</h1><p>Amount: $${invoice.amount}</p></body></html>`
11   })
12   
13   return validationJob
14 }

3. Analyze the Validation Response

The validation endpoint returns a response indicating whether the invoice can be paid with a card and lists any applicable fees.

Whether the invoice can be processed with a virtual card
The processing fee (if applicable)
Any additional requirements or restrictions

1 {
2   "canProcessWithCard": true,
3   "processingFee": 2.50,
4   "feeCurrency": "USD",
5   "restrictions": [],
6   "estimatedProcessingTime": "1-2 business days"
7 }

4. Apply Your Decision Logic

Based on the validation response, implement logic on your side to decide the next step.

If card processing isn’t available, fall back to your current workflow.
If it is available, check if the fee is within your acceptable threshold. If not, fall back.
If the fee is acceptable, proceed to process the payment with a virtual card.

JavaScript

Python

Go

Java

1 async function processPaymentDecision(invoice, validationResult) {
2   // If card processing is not available, use current workflow
3   if (validationResult.card?.eligibility !== 'ACCEPTED') {
4     return await processWithCurrentWorkflow(invoice);
5   }
6   
7   // Check if fee is acceptable (implement your threshold logic)
8   const feeThreshold = getFeeThreshold(invoice.amount);
9   const processingFee = validationResult.card?.fee?.value || 0;
10   if (processingFee > feeThreshold) {
11     return await processWithCurrentWorkflow(invoice);
12   }
13   
14   // Proceed with virtual card processing
15   return await processWithVirtualCard(invoice, validationResult);
16 }

5. Process the Payment

JavaScript

Python

Go

Java

1 async function processWithVirtualCard(invoice, validationResult) {
2   try {
3     const processJob = await mercoa.paymentGateway.createProcessJob({
4       type: "html",
5       html: `<html><body><h1>Invoice ${invoice.id}</h1><p>Amount: $${invoice.amount}</p></body></html>`,
6       cardDetails: {
7         type: "stripeIssuing",
8         firstName: "John",
9         lastName: "Doe",
10         postalCode: "12345",
11         country: "US",
12         stripeCardId: "ic_1234567890abcdef",
13         stripePublishableKey: "pk_test_1234567890abcdef",
14         ephemeralKeyEndpoint: {
15           url: "https://api.example.com/ephemeral-keys",
16           method: "POST",
17           headers: {
18             "Authorization": "Bearer YOUR_AUTH_SCHEME",
19             "Content-Type": "application/json"
20           },
21           postBody: "{\"card_id\": \"{{cardId}}\", \"nonce\": \"{{nonce}}\", \"account_id\": \"{{accountId}}\"}"
22         }
23       }
24     })
25     
26     if (processJob.jobStatus === 'success') {
27       // Reconcile the payment with your invoice
28       await reconcilePayment(invoice.id, processJob.receiptUrl);
29       return { success: true, method: 'virtual_card' };
30     } else {
31       // Fall back to current workflow
32       return await processWithCurrentWorkflow(invoice);
33     }
34   } catch (error) {
35     // Handle errors and fall back to current workflow
36     console.error('Virtual card processing failed:', error);
37     return await processWithCurrentWorkflow(invoice);
38   }
39 }

6. Reconcile the Payment

JavaScript

Python

Go

Java

1 async function reconcilePayment(invoiceId, receiptUrl) {
2   // Update your invoice status to paid
3   await updateInvoiceStatus(invoiceId, 'paid');
4   
5   // Store transaction details for audit trail
6   await storeTransactionDetails(invoiceId, receiptUrl, {
7     method: 'virtual_card',
8     processedAt: new Date(),
9     // Include other relevant transaction data
10   });
11   
12   // Trigger any post-payment workflows
13   await triggerPostPaymentWorkflows(invoiceId);
14 }

Migration Strategy

We recommend a phased approach to roll out the integration.

Phase 1: Validation Only

Implement the validation endpoint call.
Log the results to analyze vendor eligibility rates and potential fees without actually processing payments.

Phase 2: Limited Processing

Enable virtual card processing for a small, selected group of low-risk vendors or invoices.
Monitor success rates and ensure your reconciliation logic works as expected.

Phase 3: Full Integration

Enable the workflow for all eligible invoices.
Ensure your fallback mechanisms are robust.
Continuously monitor and optimize based on performance data.

1	// Example: When payment is scheduled
2	async function schedulePayment(invoice) {
3	// Your existing payment scheduling logic
4	const scheduledPayment = await createScheduledPayment(invoice);
5
6	// Call Mercoa Agent validation
7	const validationResult = await validateWithMercoaAgent(invoice);
8
9	// Store validation result for later use
10	await storeValidationResult(scheduledPayment.id, validationResult);
11
12	return scheduledPayment;
13	}

1	curl -X POST https://api.mercoa.com/payment-gateway/validate \
2	-H "Authorization: Bearer <token>" \
3	-H "Content-Type: application/json" \
4	-d '{
5	"type": "document",
6	"document": "data:application/pdf;base64,JVBERi0xLjEKJcKlwrHDqwoKMSAwIG9iagogIDw8IC9UeXBlIC9DYXRhbG9nCiAgICAgL1BhZ2VzIDIgMCBSCiAgPj4KZW5kb2JqCgoyIDAgb2JqCiAgPDwgL1R5cGUgL1BhZ2VzCiAgICAgL0tpZHMgWzMgMCBSXQogICAgIC9Db3VudCAxCiAgICAgL01lZGlhQm94IFswIDAgMzAwIDE0NF0KICA+PgplbmRvYmoKCjMgMCBvYmoKICA8PCAgL1R5cGUgL1BhZ2UKICAgICAgL1BhcmVudCAyIDAgUgogICAgICAvUmVzb3VyY2VzCiAgICAgICA8PCAvRm9udAogICAgICAgICAgIDw8IC9GMQogICAgICAgICAgICAgICA8PCAvVHlwZSAvRm9udAogICAgICAgICAgICAgICAgICAvU3VidHlwZSAvVHlwZTEKICAgICAgICAgICAgICAgICAgL0Jhc2VGb250IC9UaW1lcy1Sb21hbgogICAgICAgICAgICAgICA+PgogICAgICAgICAgID4+CiAgICAgICA+PgogICAgICAvQ29udGVudHMgNCAwIFIKICA+PgplbmRvYmoKCjQgMCBvYmoKICA8PCAvTGVuZ3RoIDU1ID4+CnN0cmVhbQogIEJUCiAgICAvRjEgMTggVGYKICAgIDAgMCBUZAogICAgKEhlbGxvIFdvcmxkKSBUagogIEVUCmVuZHN0cmVhbQplbmRvYmoKCnhyZWYKMCA1CjAwMDAwMDAwMDAgNjU1MzUgZiAKMDAwMDAwMDAxOCAwMDAwMCBuIAowMDAwMDAwMDc3IDAwMDAwIG4gCjAwMDAwMDAxNzggMDAwMDAgbiAKMDAwMDAwMDQ1NyAwMDAwMCBuIAp0cmFpbGVyCiAgPDwgIC9Sb290IDEgMCBSCiAgICAgIC9TaXplIDUKICA+PgpzdGFydHhyZWYKNTY1CiUlRU9GCg=="
7	}'

1	import { MercoaClient } from "@mercoa/javascript"
2
3	const mercoa = new MercoaClient({
4	token: "YOUR_API_KEY",
5	})
6
7	async function validateWithMercoaAgent(invoice) {
8	const validationJob = await mercoa.paymentGateway.createValidationJob({
9	type: "html",
10	html: `<html><body><h1>Invoice ${invoice.id}</h1><p>Amount: $${invoice.amount}</p></body></html>`
11	})
12
13	return validationJob
14	}

1	{
2	"canProcessWithCard": true,
3	"processingFee": 2.50,
4	"feeCurrency": "USD",
5	"restrictions": [],
6	"estimatedProcessingTime": "1-2 business days"
7	}

1	async function processPaymentDecision(invoice, validationResult) {
2	// If card processing is not available, use current workflow
3	if (validationResult.card?.eligibility !== 'ACCEPTED') {
4	return await processWithCurrentWorkflow(invoice);
5	}
6
7	// Check if fee is acceptable (implement your threshold logic)
8	const feeThreshold = getFeeThreshold(invoice.amount);
9	const processingFee = validationResult.card?.fee?.value \|\| 0;
10	if (processingFee > feeThreshold) {
11	return await processWithCurrentWorkflow(invoice);
12	}
13
14	// Proceed with virtual card processing
15	return await processWithVirtualCard(invoice, validationResult);
16	}

1	async function processWithVirtualCard(invoice, validationResult) {
2	try {
3	const processJob = await mercoa.paymentGateway.createProcessJob({
4	type: "html",
5	html: `<html><body><h1>Invoice ${invoice.id}</h1><p>Amount: $${invoice.amount}</p></body></html>`,
6	cardDetails: {
7	type: "stripeIssuing",
8	firstName: "John",
9	lastName: "Doe",
10	postalCode: "12345",
11	country: "US",
12	stripeCardId: "ic_1234567890abcdef",
13	stripePublishableKey: "pk_test_1234567890abcdef",
14	ephemeralKeyEndpoint: {
15	url: "https://api.example.com/ephemeral-keys",
16	method: "POST",
17	headers: {
18	"Authorization": "Bearer YOUR_AUTH_SCHEME",
19	"Content-Type": "application/json"
20	},
21	postBody: "{\"card_id\": \"{{cardId}}\", \"nonce\": \"{{nonce}}\", \"account_id\": \"{{accountId}}\"}"
22	}
23	}
24	})
25
26	if (processJob.jobStatus === 'success') {
27	// Reconcile the payment with your invoice
28	await reconcilePayment(invoice.id, processJob.receiptUrl);
29	return { success: true, method: 'virtual_card' };
30	} else {
31	// Fall back to current workflow
32	return await processWithCurrentWorkflow(invoice);
33	}
34	} catch (error) {
35	// Handle errors and fall back to current workflow
36	console.error('Virtual card processing failed:', error);
37	return await processWithCurrentWorkflow(invoice);
38	}
39	}

1	async function reconcilePayment(invoiceId, receiptUrl) {
2	// Update your invoice status to paid
3	await updateInvoiceStatus(invoiceId, 'paid');
4
5	// Store transaction details for audit trail
6	await storeTransactionDetails(invoiceId, receiptUrl, {
7	method: 'virtual_card',
8	processedAt: new Date(),
9	// Include other relevant transaction data
10	});
11
12	// Trigger any post-payment workflows
13	await triggerPostPaymentWorkflows(invoiceId);
14	}