Invoice

Create

POST
https://api.mercoa.com/invoice

Request

This endpoint expects an object.
status
optional enum
amount
optional double

Total amount of invoice in major units. If the entered amount has more decimal places than the currency supports, trailing decimals will be truncated.

currency
optional enum

Currency code for the amount. Defaults to USD.

invoiceDate
optional datetime

Date the invoice was issued.

deductionDate
optional datetime

Date when funds will be deducted from payer's account.

settlementDate
optional datetime

Date of funds settlement.

dueDate
optional datetime

Due date of invoice.

invoiceNumber
optional string
noteToSelf
optional string

Note to self or memo on invoice.

serviceStartDate
optional datetime
serviceEndDate
optional datetime
payerId
optional string
paymentSourceId
optional string

ID of payment source for this invoice. If not provided, will attempt to use the default payment source for the payer when creating an invoice if a default payment source exists for the payer.

vendorId
optional string
paymentDestinationId
optional string

ID of payment destination for this invoice. If not provided, will attempt to use the default payment destination for the vendor when creating an invoice if a default payment destination exists for the vendor.

paymentDestinationOptions
optional union

Options for the payment destination. Depending on the payment destination, this may include things such as check delivery method.

approvers
optional list of objects

Set approvers for this invoice.

lineItems
optional list of objects
metadata
optional map from strings to strings

Metadata associated with this invoice. You can specify up to 10 keys, with key names up to 40 characters long and values up to 200 characters long.

foreignId
optional string

The ID used to identify this invoice in your system. This ID must be unique within each creatorEntity in your system, e.g. two invoices with the same creatorEntity may not have the same foreign ID.

uploadedImage
optional string

Base64 encoded image or PDF of invoice. PNG, JPG, and PDF are supported. 10MB max.

creatorEntityId
optional string

ID of entity who created this invoice.

creatorUserId
optional string

ID of entity user who created this invoice.

Response

This endpoint return an object.
id
string
status
enum
paymentDestinationConfirmed
boolean

True if the payment destination has been confirmed by the vendor. False if the payment destination has been set (for example, a check to an address) but has not been confirmed by the vendor.

hasDocuments
boolean

True if the invoice has documents attached.

approvers
list of objects
approvalPolicy
list of objects
metadata
map from strings to strings

Metadata associated with this invoice.

createdAt
datetime
updatedAt
datetime
amount
optional double

Total amount of invoice in major units

currency
optional enum

Currency code for the amount. Defaults to USD.

invoiceDate
optional datetime

Date the invoice was issued.

deductionDate
optional datetime

Date when funds will be deducted from payer's account.

settlementDate
optional datetime

Date of funds settlement.

dueDate
optional datetime

Due date of invoice.

invoiceNumber
optional string
noteToSelf
optional string
serviceStartDate
optional datetime
serviceEndDate
optional datetime
payerId
optional string
payer
optional object
paymentSource
optional union
paymentSourceId
optional string
vendorId
optional string
vendor
optional object
paymentDestination
optional union
paymentDestinationId
optional string
paymentDestinationOptions
optional union
comments
optional list of objects
lineItems
optional list of objects
foreignId
optional string

The ID used to identify this invoice in your system. This ID must be unique within each creatorEntity in your system, e.g. two invoices with the same creatorEntity may not have the same foreign ID.

creatorUser
optional object

Entity user who created this invoice.

failureType
optional enum

If the invoice failed to be paid, this field will be populated with the type of failure.

Allowed values: SOURCE_PAYMENT_ERRORDESTINATION_PAYMENT_ERRORREJECTED_HIGH_RISKINSUFFICIENT_FUNDSPROCESSING_ERROR
processedAt
optional datetime
fees
optional object

Fees associated with this invoice.

POST
/invoice
curl -X POST https://api.mercoa.com/invoice \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{}'
Response
{
"id": "string",
"status": "DRAFT",
"paymentDestinationConfirmed": true,
"hasDocuments": true,
"approvers": [
{
"approvalPolicyId": "string",
"approvalSlotId": "string",
"action": "NONE",
"eligibleRoles": [
"string"
],
"eligibleUserIds": [
"string"
],
"date": "2023-01-01T00:00:00Z",
"assignedUserId": "string"
}
],
"approvalPolicy": [
{
"id": "string",
"trigger": [
{
"type": "amount",
"amount": 1,
"currency": "AED"
}
],
"rule": {
"type": "approver",
"identifierList": {
"type": "rolesList",
"value": [
"string"
]
},
"numApprovers": 0
},
"upstreamPolicyId": "string"
}
],
"metadata": {
"string": "string"
},
"createdAt": "2023-01-01T00:00:00Z",
"updatedAt": "2023-01-01T00:00:00Z",
"amount": 1,
"currency": "AED",
"invoiceDate": "2023-01-01T00:00:00Z",
"deductionDate": "2023-01-01T00:00:00Z",
"settlementDate": "2023-01-01T00:00:00Z",
"dueDate": "2023-01-01T00:00:00Z",
"invoiceNumber": "string",
"noteToSelf": "string",
"serviceStartDate": "2023-01-01T00:00:00Z",
"serviceEndDate": "2023-01-01T00:00:00Z",
"payerId": "string",
"payer": {
"id": "string",
"name": "string",
"email": "string",
"isCustomer": true,
"accountType": "business",
"profile": {
"business": {
"legalBusinessName": "string",
"taxIDProvided": true,
"email": "string",
"businessType": "soleProprietorship",
"phone": {
"countryCode": "string",
"number": "string"
},
"doingBusinessAs": "string",
"website": "string",
"description": "string",
"address": {
"addressLine1": "string",
"city": "string",
"stateOrProvince": "string",
"postalCode": "string",
"addressLine2": "string",
"country": "string"
},
"ownersProvided": true
},
"individual": {
"email": "string",
"name": {
"firstName": "string",
"lastName": "string",
"middleName": "string",
"suffix": "string"
},
"birthDateProvided": true,
"governmentIDProvided": true,
"phone": {
"countryCode": "string",
"number": "string"
},
"address": {
"addressLine1": "string",
"city": "string",
"stateOrProvince": "string",
"postalCode": "string",
"addressLine2": "string",
"country": "string"
}
}
},
"status": "unverified",
"acceptedTos": true,
"isPayor": true,
"isPayee": true,
"createdAt": "2023-01-01T00:00:00Z",
"updatedAt": "2023-01-01T00:00:00Z",
"foreignId": "string",
"emailTo": "string",
"emailToAlias": [
"string"
]
},
"paymentSource": {
"type": "bankAccount",
"accountName": "string",
"accountNumber": "string",
"accountType": "CHECKING",
"bankName": "string",
"createdAt": "2023-01-01T00:00:00Z",
"id": "string",
"isDefaultDestination": true,
"isDefaultSource": true,
"routingNumber": "string",
"status": "NEW",
"supportedCurrencies": [
"AED"
],
"updatedAt": "2023-01-01T00:00:00Z",
"checkOptions": {
"enabled": true,
"initialCheckNumber": 0,
"routingNumberOverride": "string",
"accountNumberOverride": "string",
"signatoryName": "string",
"signatureImage": "string"
}
},
"paymentSourceId": "string",
"vendorId": "string",
"vendor": {
"id": "string",
"name": "string",
"email": "string",
"isCustomer": true,
"accountType": "business",
"profile": {
"business": {
"legalBusinessName": "string",
"taxIDProvided": true,
"email": "string",
"businessType": "soleProprietorship",
"phone": {
"countryCode": "string",
"number": "string"
},
"doingBusinessAs": "string",
"website": "string",
"description": "string",
"address": {
"addressLine1": "string",
"city": "string",
"stateOrProvince": "string",
"postalCode": "string",
"addressLine2": "string",
"country": "string"
},
"ownersProvided": true
},
"individual": {
"email": "string",
"name": {
"firstName": "string",
"lastName": "string",
"middleName": "string",
"suffix": "string"
},
"birthDateProvided": true,
"governmentIDProvided": true,
"phone": {
"countryCode": "string",
"number": "string"
},
"address": {
"addressLine1": "string",
"city": "string",
"stateOrProvince": "string",
"postalCode": "string",
"addressLine2": "string",
"country": "string"
}
}
},
"status": "unverified",
"acceptedTos": true,
"isPayor": true,
"isPayee": true,
"createdAt": "2023-01-01T00:00:00Z",
"updatedAt": "2023-01-01T00:00:00Z",
"foreignId": "string",
"emailTo": "string",
"emailToAlias": [
"string"
]
},
"paymentDestination": {
"type": "bankAccount",
"accountName": "string",
"accountNumber": "string",
"accountType": "CHECKING",
"bankName": "string",
"createdAt": "2023-01-01T00:00:00Z",
"id": "string",
"isDefaultDestination": true,
"isDefaultSource": true,
"routingNumber": "string",
"status": "NEW",
"supportedCurrencies": [
"AED"
],
"updatedAt": "2023-01-01T00:00:00Z",
"checkOptions": {
"enabled": true,
"initialCheckNumber": 0,
"routingNumberOverride": "string",
"accountNumberOverride": "string",
"signatoryName": "string",
"signatureImage": "string"
}
},
"paymentDestinationId": "string",
"paymentDestinationOptions": {
"type": "check",
"delivery": "PRINT"
},
"comments": [
{
"id": "string",
"text": "string",
"createdAt": "2023-01-01T00:00:00Z",
"updatedAt": "2023-01-01T00:00:00Z",
"user": {
"id": "string",
"roles": [
"string"
],
"createdAt": "2023-01-01T00:00:00Z",
"updatedAt": "2023-01-01T00:00:00Z",
"foreignId": "string",
"email": "string",
"name": "string"
},
"associatedApprovalAction": {
"userId": "string",
"action": "NONE"
}
}
],
"lineItems": [
{
"id": "string",
"currency": "AED",
"createdAt": "2023-01-01T00:00:00Z",
"updatedAt": "2023-01-01T00:00:00Z",
"amount": 1,
"description": "string",
"name": "string",
"quantity": 0,
"unitPrice": 1,
"serviceStartDate": "2023-01-01T00:00:00Z",
"serviceEndDate": "2023-01-01T00:00:00Z",
"metadata": {
"string": "string"
},
"glAccountId": "string"
}
],
"foreignId": "string",
"creatorUser": {
"id": "string",
"roles": [
"string"
],
"createdAt": "2023-01-01T00:00:00Z",
"updatedAt": "2023-01-01T00:00:00Z",
"foreignId": "string",
"email": "string",
"name": "string"
},
"failureType": "SOURCE_PAYMENT_ERROR",
"processedAt": "2023-01-01T00:00:00Z",
"fees": {
"sourcePaymentMethodFee": 1,
"sourcePlatformMarkupFee": 1,
"destinationPaymentMethodFee": 1,
"destinationPlatformMarkupFee": 1
}
}