Vic.ai Credit Confirmations API
Confirm or mark credits as failed after processing in your ERP.
OpenAPI Specification
openapi: 3.1.0
info:
version: v10.40.4
contact: {}
title: Vic.ai Accounts Credit Confirmations API
description: "## Introduction\n\nThe Vic.ai API provides a seamless connection between your Enterprise Resource\nPlanning (ERP) system and the Vic.ai product suite.\n\nThe API is designed to offer three main areas of functionality:\n\n- **Syncing master data:** This refers to the data in your ERP that Vic.ai\n interacts with. You are required to supply and update this data in Vic.ai, and\n you also have the option to verify the copy of the masterdata in Vic.ai.\n\n- **Syncing training data:** We need historical data to train your AI model. To\n that end, the API provides endpoints to sync historical invoices into Vic.ai\n and to confirm their presence.\n\n- **Subscribing to and receiving webhooks:** Webhooks enable users or automated\n tasks to interact with your ERP through various actions in the Vic.ai product\n suite, such as posting an invoice, payment or purchase order or requesting\n synchronization. You will receive a notification via a webhook when these\n actions occur.\n\n\nFor US-based integrations, please use the following base API URL:\n\n```\nhttps://api.us.vic.ai\n```\n\nFor integrations based in Norway, use the following base API URL:\n\n```\nhttps://api.no.vic.ai\n```\n\nAll paths mentioned in this documentation should use one of these URLs as the\nbase.\n\nExample:\n\n```bash\ncurl https://api.us.vic.ai/v0/healthCheck \\\n -H \"Content-Type: application/json\" \\\n -H \"Authorization: Bearer YOUR_ACCESS_TOKEN\"\n```\n\n## Getting Started\n\nTo begin interacting with the Vic.ai API, you will need the following\ncredentials:\n\n* A Vic.ai client ID\n* A Vic.ai client secret.\n\nThese can be provided to you securely by a Vic.ai representative\n[upon request](https://www.vic.ai/book-a-demo).\n\n**Please note:** These credentials are essentially the keys to your ERP\nintegration. If they fall into the wrong hands, unauthorized parties could\nimpersonate you, gain access to sensitive data, and potentially perform\nmalicious actions. Therefore, it's crucial to keep these credentials safe at all\ntimes to protect your application's integrity and your clients' data.\n\n### Limitations\n\nThe Vic.ai API has the following limitations:\n\n**Rate Limiting:** The API is rate-limited to 500 requests per 10-second time\nframe. If you exceed this limit, you will receive a `429 Too Many Requests`\nresponse. The limit is per Oauth client ID. If you continue to receive `429`s,\nplease contact support with a request id from the response headers.\n"
servers:
- url: https://api.no.stage.vic.ai
description: staging server, NO
- url: https://api.us.vic.ai
description: production server, US
- url: https://api.no.vic.ai
description: production server, NO
security:
- BearerAuth: []
tags:
- name: Credit Confirmations
description: Confirm or mark credits as failed after processing in your ERP.
paths:
/v0/credits/{id}/confirm:
post:
description: 'Confirms a single credit by setting the `confirmedAt` timestamp and
optionally setting a `remoteId`. This is used to mark a credit as
confirmed in an external system.
'
summary: Confirm a credit
operationId: confirmCredit
tags:
- Credit Confirmations
parameters:
- name: id
in: path
required: true
description: The id of the credit.
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ConfirmCreditInput'
responses:
'200':
$ref: '#/components/responses/CreditConfirmedResponse'
'403':
$ref: '#/components/responses/ForbiddenResponse'
'404':
$ref: '#/components/responses/ResourceNotFoundResponse'
'422':
$ref: '#/components/responses/UnprocessableEntityResponse'
'429':
$ref: '#/components/responses/TooManyRequestsResponse'
4XX:
$ref: '#/components/responses/ErrorResponse'
/v0/credits/confirm:
post:
description: 'Bulk confirms multiple credits in a single request. Each credit in the
request body must include an `id`, `confirmedAt` timestamp, and
optionally a `remoteId`.
If a credit is not found, the entire bulk confirmation is aborted.
'
summary: Bulk confirm credits
operationId: bulkConfirmCredits
tags:
- Credit Confirmations
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BulkConfirmCreditsInput'
responses:
'200':
$ref: '#/components/responses/CreditsBulkConfirmedResponse'
'403':
$ref: '#/components/responses/ForbiddenResponse'
'404':
$ref: '#/components/responses/ResourceNotFoundResponse'
'422':
$ref: '#/components/responses/UnprocessableEntityResponse'
'429':
$ref: '#/components/responses/TooManyRequestsResponse'
4XX:
$ref: '#/components/responses/ErrorResponse'
/v0/credits/{id}/fail:
post:
description: 'Marks a credit as having a remote error by setting the `remoteErroredAt`
timestamp and `remoteError` message. Optionally sets a `remoteId`. This
clears any existing `confirmedAt` timestamp.
**Note**: When providing an error, please provide a clear error message
that the user can understand.
'
summary: Mark credit as failed
operationId: failCredit
tags:
- Credit Confirmations
parameters:
- name: id
in: path
required: true
description: The id of the credit.
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/FailCreditInput'
responses:
'200':
$ref: '#/components/responses/CreditFailedResponse'
'403':
$ref: '#/components/responses/ForbiddenResponse'
'404':
$ref: '#/components/responses/ResourceNotFoundResponse'
'422':
$ref: '#/components/responses/UnprocessableEntityResponse'
'429':
$ref: '#/components/responses/TooManyRequestsResponse'
4XX:
$ref: '#/components/responses/ErrorResponse'
/v0/credits/fail:
post:
description: 'Bulk marks multiple credits as having remote errors in a single request.
Each credit in the request body must include an `id`, `remoteErroredAt`
timestamp, `remoteError` message, and optionally a `remoteId`.
**Note**: When providing an error, please provide a clear error message
that the user can understand.
If a credit is not found, the entire bulk operation is aborted.
'
summary: Bulk fail credits
operationId: bulkFailCredits
tags:
- Credit Confirmations
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BulkFailCreditsInput'
responses:
'200':
$ref: '#/components/responses/CreditsBulkFailedResponse'
'403':
$ref: '#/components/responses/ForbiddenResponse'
'404':
$ref: '#/components/responses/ResourceNotFoundResponse'
'422':
$ref: '#/components/responses/UnprocessableEntityResponse'
'429':
$ref: '#/components/responses/TooManyRequestsResponse'
4XX:
$ref: '#/components/responses/ErrorResponse'
/v2/companies/{company_id}/credits/{id}/confirm:
parameters:
- $ref: '#/components/parameters/CompanyId'
post:
description: 'Confirms a single credit by setting the `confirmed_at` timestamp and
optionally setting a `remote_id`. This is used to mark a credit as
confirmed in an external system.
'
summary: Confirm a credit
operationId: confirmCreditV2
tags:
- Credit Confirmations
x-badges:
- name: V2
position: after
color: blue
parameters:
- name: id
in: path
required: true
description: The id of the credit.
schema:
type: string
format: uuid
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ConfirmCreditInputV2'
responses:
'200':
$ref: '#/components/responses/CreditConfirmedResponseV2'
'403':
$ref: '#/components/responses/ForbiddenResponse'
'404':
$ref: '#/components/responses/ResourceNotFoundResponse'
'422':
$ref: '#/components/responses/UnprocessableEntityResponse'
4XX:
$ref: '#/components/responses/ErrorResponseV2'
/v2/companies/{company_id}/credits/confirm:
parameters:
- $ref: '#/components/parameters/CompanyId'
post:
description: 'Bulk confirms multiple credits in a single request. Each credit in the
request body must include an `id`, `confirmed_at` timestamp, and
optionally a `remote_id`.
If a credit is not found, the entire bulk confirmation is aborted.
'
summary: Bulk confirm credits
operationId: bulkConfirmCreditsV2
tags:
- Credit Confirmations
x-badges:
- name: V2
position: after
color: blue
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BulkConfirmCreditsInputV2'
responses:
'200':
$ref: '#/components/responses/CreditsBulkConfirmedResponseV2'
'403':
$ref: '#/components/responses/ForbiddenResponse'
'404':
$ref: '#/components/responses/ResourceNotFoundResponse'
'422':
$ref: '#/components/responses/UnprocessableEntityResponse'
4XX:
$ref: '#/components/responses/ErrorResponseV2'
/v2/companies/{company_id}/credits/{id}/fail:
parameters:
- $ref: '#/components/parameters/CompanyId'
- name: id
in: path
required: true
description: The id of the credit.
schema:
type: string
format: uuid
post:
description: 'Marks a credit as having a remote error by setting the `remote_errored_at`
timestamp and `remote_error` message. Optionally sets a `remote_id`. This
clears any existing `confirmed_at` timestamp.
**Note**: When providing an error, please provide a clear error message
that the user can understand.
'
summary: Mark credit as failed
operationId: failCreditV2
tags:
- Credit Confirmations
x-badges:
- name: V2
position: after
color: blue
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/FailCreditInputV2'
responses:
'200':
$ref: '#/components/responses/CreditFailedResponseV2'
'403':
$ref: '#/components/responses/ForbiddenResponse'
'404':
$ref: '#/components/responses/ResourceNotFoundResponse'
'422':
$ref: '#/components/responses/UnprocessableEntityResponse'
4XX:
$ref: '#/components/responses/ErrorResponseV2'
/v2/companies/{company_id}/credits/fail:
parameters:
- $ref: '#/components/parameters/CompanyId'
post:
description: 'Bulk marks multiple credits as having remote errors in a single request.
Each credit in the request body must include an `id`, `remote_errored_at`
timestamp, `remote_error` message, and optionally a `remote_id`.
**Note**: When providing an error, please provide a clear error message
that the user can understand.
If a credit is not found, the entire bulk operation is aborted.
'
summary: Bulk fail credits
operationId: bulkFailCreditsV2
tags:
- Credit Confirmations
x-badges:
- name: V2
position: after
color: blue
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/BulkFailCreditsInputV2'
responses:
'200':
$ref: '#/components/responses/CreditsBulkFailedResponseV2'
'403':
$ref: '#/components/responses/ForbiddenResponse'
'404':
$ref: '#/components/responses/ResourceNotFoundResponse'
'422':
$ref: '#/components/responses/UnprocessableEntityResponse'
4XX:
$ref: '#/components/responses/ErrorResponseV2'
components:
schemas:
Credit:
type: object
properties:
id:
type: string
format: uuid
description: The id of the credit.
batchId:
type: string
format: uuid
description: The id of the payment batch the credit belongs to.
amount:
$ref: '#/components/schemas/MonetaryValue'
settlementAmount:
$ref: '#/components/schemas/MonetaryValue'
currencyId:
$ref: '#/components/schemas/Currency'
settlementCurrencyId:
$ref: '#/components/schemas/Currency'
exchangeRate:
$ref: '#/components/schemas/MonetaryValue'
status:
$ref: '#/components/schemas/CreditStatus'
paymentMethod:
oneOf:
- $ref: '#/components/schemas/PaymentMethod'
- type: 'null'
referenceId:
oneOf:
- $ref: '#/components/schemas/PaymentReferenceId'
- type: 'null'
approvedAt:
oneOf:
- type: string
format: date-time
description: The payment approver has approved the credit.
- type: 'null'
fundedAt:
oneOf:
- type: string
format: date-time
description: 'The date time the payment request began to be processed.
**Note**: This is not the actual date time that the funds were
withdrawn from the bank. The payment request can take 15
minutes to 4 hours or more to be processed. See the `acceptedAt`
field for the date time that the payment was submitted and
accepted.
'
- type: 'null'
failedAt:
type:
- string
- 'null'
format: date-time
description: When the credit was marked as failed.
failedReason:
type:
- string
- 'null'
description: The reason why the credit failed.
acceptedAt:
oneOf:
- type: string
format: date-time
description: 'The date time the payment request was submitted and accepted
for processing.
'
- type: 'null'
rejectedAt:
oneOf:
- type: string
format: date-time
description: The payment approver has rejected the credit payment.
- type: 'null'
voidedAt:
oneOf:
- type: string
format: date-time
description: 'This is set when a credit has been voided by the payment processor.
Generally this would happen due to a `Vendor` missing address
information or a malformed `Invoice` was trying to be paid. Other
cases could cause this to be voided due to insufficient funds.
'
- type: 'null'
confirmedAt:
oneOf:
- type: string
format: date-time
description: The datetime when the credit was confirmed in an external system.
- type: 'null'
remoteId:
oneOf:
- type: string
maxLength: 255
description: An external identifier for the credit in the confirming system.
- type: 'null'
remoteError:
oneOf:
- type: string
description: An error message if the confirmation failed.
- type: 'null'
remoteErroredAt:
oneOf:
- type: string
format: date-time
description: When the remote error occurred.
- type: 'null'
invoice:
$ref: '#/components/schemas/InvoiceRef'
costAccount:
$ref: '#/components/schemas/CostAccountRef'
vendor:
$ref: '#/components/schemas/VendorRef'
PaymentMethod:
type: string
enum:
- ach
- card
- check
- wire
PaymentStatus:
type: string
enum:
- pending_approval
- rejected
- approved
- acknowledged
- voided
- failed
description: "The status of the payment.\n- `pending_approval` - The payment is awaiting approval.\n- `approved` - The payment was approved for payment.\n- `rejected` - The payment was rejected and was excluded from being paid.\n- `acknowledged` - The `rejected` payment was acknowledged by the payee.\n- `voided` - The payment was voided for reason.\n- `failed` - The payment failed to be submitted to the payment provider.\n See the failed reason for more information.\n"
BulkFailCreditsInputV2:
type: object
description: Input schema for bulk failing multiple credits (V2 API with snake_case fields).
required:
- credits
properties:
credits:
type: array
minItems: 1
maxItems: 100
description: Array of credit failure items. Must contain at least one item.
items:
type: object
required:
- id
- remote_errored_at
- remote_error
properties:
id:
type: string
format: uuid
description: The UUID of the credit to mark as failed.
remote_errored_at:
type: string
format: date-time
description: The datetime when the credit failed in the external system.
remote_error:
type: string
maxLength: 255
description: 'The error message describing why the credit failed. This message will be displayed
to the user. It should be clear as to what happened so that it can be rectified.
'
remote_id:
type:
- string
- 'null'
maxLength: 255
description: An optional external identifier for the failed credit.
ErrorV2:
type: object
required:
- message
properties:
field:
description: 'The field that the error occurred on. This field may not always be
present.
'
oneOf:
- type: string
- type: 'null'
message:
description: A description of the error.
type: string
BulkFailCreditsInput:
type: object
description: Input schema for bulk failing multiple credits.
required:
- credits
properties:
credits:
type: array
minItems: 1
maxItems: 100
description: Array of credit failure items. Must contain at least one item.
items:
type: object
required:
- id
- remoteErroredAt
- remoteError
properties:
id:
type: string
format: uuid
description: The UUID of the credit to mark as failed.
remoteErroredAt:
type: string
format: date-time
description: The datetime when the credit failed in the external system.
remoteError:
type: string
maxLength: 255
description: 'The error message describing why the credit failed. This message will be displayed
to the user. It should be clear as to what happened so that it can be rectified.
'
remoteId:
type:
- string
- 'null'
maxLength: 255
description: An optional external identifier for the failed credit.
FailCreditInput:
type: object
description: Input schema for marking a credit as failed.
required:
- remoteErroredAt
- remoteError
properties:
remoteErroredAt:
type: string
format: date-time
description: The datetime when the credit failed in the external system.
remoteError:
type: string
maxLength: 255
description: 'The error message describing why the credit failed. This message will be displayed to
the user. It should be clear as to what happened so that it can be rectified.
'
remoteId:
type:
- string
- 'null'
maxLength: 255
description: An optional external identifier for the failed credit.
FailCreditInputV2:
type: object
description: Input schema for marking a credit as failed (V2 API with snake_case fields).
required:
- remote_errored_at
- remote_error
properties:
remote_errored_at:
type: string
format: date-time
description: The datetime when the credit failed in the external system.
remote_error:
type: string
maxLength: 255
description: 'The error message describing why the credit failed. This message will be displayed
to the user. It should be clear as to what happened so that it can be rectified.
'
remote_id:
type:
- string
- 'null'
maxLength: 255
description: An optional external identifier for the failed credit.
VendorRef:
type: object
description: A reference to a `Vendor`.
properties:
internalId:
oneOf:
- $ref: '#/components/schemas/VendorInternalId'
- type: 'null'
externalId:
oneOf:
- $ref: '#/components/schemas/ExternalId'
- type: 'null'
ExternalId:
description: 'The external id set by the ERP system. It does not have to be a UUID and
can be any non empty string desired.
'
type: string
example: 21b31bc7-1267-4335-893c-d7fe4706a238
maxLength: 255
BulkConfirmCreditsInputV2:
type: object
description: Input schema for bulk confirming multiple credits (V2 API with snake_case fields).
required:
- credits
properties:
credits:
type: array
minItems: 1
maxItems: 100
description: Array of credit confirmation items. Must contain at least one item and no more than 100 items.
items:
type: object
required:
- id
- confirmed_at
properties:
id:
type: string
format: uuid
description: The UUID of the credit to confirm.
confirmed_at:
type: string
format: date-time
description: The datetime when the credit was confirmed in the external system.
remote_id:
type:
- string
- 'null'
maxLength: 255
description: An optional external identifier for the credit in the confirming system.
InvoiceInternalId:
type: string
description: The id of the `Invoice` in Vic.
maxLength: 255
ConfirmCreditInput:
type: object
description: Input schema for confirming a credit.
required:
- confirmedAt
properties:
confirmedAt:
type: string
format: date-time
description: The datetime when the credit was confirmed in the external system.
remoteId:
type:
- string
- 'null'
maxLength: 255
description: An optional external identifier for the credit in the confirming system.
Currency:
description: The ISO-4217 currency code.
type: string
format: ISO-4217
maxLength: 3
example: USD
PaymentReferenceId:
type: string
description: 'The reference id of the payment or credit is associated with. This will
be the identifier is on the remittance advice sent to the Vendor.
Example: `P001234`, `A000134`, or `E123456`
'
BulkConfirmCreditsInput:
type: object
description: Input schema for bulk confirming multiple credits.
required:
- credits
properties:
credits:
type: array
minItems: 1
description: Array of credit confirmation items. Must contain at least one item.
items:
type: object
required:
- id
- confirmedAt
properties:
id:
type: string
format: uuid
description: The UUID of the credit to confirm.
confirmedAt:
type: string
format: date-time
description: The datetime when the credit was confirmed in the external system.
remoteId:
type:
- string
- 'null'
maxLength: 255
description: An optional external identifier for the credit in the confirming system.
ConfirmCreditInputV2:
type: object
description: Input schema for confirming a credit (V2 API with snake_case fields).
required:
- confirmed_at
properties:
confirmed_at:
type: string
format: date-time
description: The datetime when the credit was confirmed in the external system.
remote_id:
type:
- string
- 'null'
maxLength: 255
description: An optional external identifier for the credit in the confirming system.
VendorInternalId:
type: string
description: The id of the `Vendor` in Vic.
maxLength: 255
ErrorString:
type: string
maxLength: 255
Error:
description: 'generic error message in JSON format. Note the ''code'' field should
match the HTTP status code of the wrapping HTTP request.
'
type: object
required:
- code
- message
properties:
code:
type: integer
minimum: 100
maximum: 599
message:
$ref: '#/components/schemas/ErrorString'
InvoiceRef:
type: object
description: A reference to an `Invoice`.
properties:
internalId:
oneOf:
- $ref: '#/components/schemas/InvoiceInternalId'
- type: 'null'
externalId:
oneOf:
- $ref: '#/components/schemas/ExternalId'
- type: 'null'
refNumber:
type:
- string
- 'null'
CreditStatus:
type: string
enum:
- pending_approval
- rejected
- approved
- acknowledged
- voided
MonetaryValue:
description: 'The monetary value as a string.
A float **should not** be used. The api will accept a float and it will be
transformed into a monetary value, but for best results please use a string
with the proper decimal precision.
'
type: string
format: decimal
example: '1.00'
CostAccountRef:
type: object
description: A reference to a `Account`.
properties:
internalId:
oneOf:
- type: string
maxLength: 255
description: The id of the `Account` in Vic.
- type: 'null'
externalId:
oneOf:
- $ref: '#/components/schemas/ExternalId'
- type: 'null'
CreditV2:
type: object
description: A credit payment in the V2 API format with snake_case field names.
properties:
id:
type: string
format: uuid
description: The unique identifier of the credit.
amount:
type: string
description: The credit amount as a decimal string.
approved_at:
type:
- string
- 'null'
format: date-time
description: The datetime when the credit was approved.
confirmed_at:
type:
- string
- 'null'
format: date-time
description: The datetime when the credit was confirmed.
currency_id:
type: string
description: The ISO 4217 currency code.
exchange_rate:
type:
- string
- 'null'
description: The exchange rate used for the credit.
failed_at:
type:
- string
- 'null'
format: date-time
description: The datetime when the credit failed.
failed_reason:
type:
- string
- 'null'
description: The reason why the credit failed
funded_at:
type:
- string
- 'null'
format: date-time
description: The datetime when funding began.
accepted_at:
type:
- string
- 'null'
format: date-time
description: The datetime when the credit was accepted for processing.
payment_method:
type:
- string
- 'null'
description: The payment method used.
reference_id:
type:
- string
- 'null'
description: The reference identifier for the credit.
rejected_at:
type:
- string
- 'null'
format: date-time
description: The datetime when the credit was rejected.
remote_error:
type:
- string
- 'null'
description: Error message if confirmation failed.
remote_errored_at:
type:
- string
- 'null'
format: date-time
description: When the remote error occurred.
remote_id:
type:
- string
- 'null'
description: External system identifier for the credit.
settlement_amount:
type:
- string
- 'null'
description: The settlement amount as a decimal string.
settlement_currency_id:
type:
- string
- 'null'
description: The settlement currency ISO code.
status:
$ref: '#/components/schemas/PaymentStatus'
voided_at:
type:
- string
- 'null'
format: date-time
description: The datetime when the credit was voided.
created_at:
type: string
format: date-time
description: The datetime when the credit was created.
updated_at:
type: string
format: date-time
description: The datetime when the credit was last updated.
responses:
CreditsBulkFailedResponseV2:
description: Credits bulk failed successfully.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/CreditV2'
CreditsBulkConfirmedResponseV2:
description: Credits bulk confirmed successfully.
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/CreditV2'
ErrorResponse:
description: An unexpected error has occurred. Check the body for more details.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
TooManyRequestsResponse:
descri
# --- truncated at 32 KB (35 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/vicai/refs/heads/main/openapi/vicai-credit-confirmations-api-openapi.yml