MX Technologies microdeposits API
The microdeposits API from MX Technologies — 4 operation(s) for microdeposits.
OpenAPI Specification
openapi: 3.0.0
info:
contact:
name: MX Platform API
url: https://www.mx.com/products/platform-api
description: 'The MX Platform API is a powerful, fully-featured API designed to make aggregating and enhancing financial data easy and reliable. It can seamlessly connect your app or website to tens of thousands of financial institutions.
Just getting started? See our [use case guides](/use-cases/).
'
title: MX Platform accounts microdeposits API
version: '20111101'
servers:
- url: https://int-api.mx.com
- url: https://api.mx.com
security:
- basicAuth: []
tags:
- name: microdeposits
paths:
/users/{user_guid}/micro_deposits:
get:
tags:
- microdeposits
operationId: listUserMicrodeposits
summary: List all microdeposits for a user
description: Use this endpoint to read the attributes of a specific microdeposit according to its unique GUID.
parameters:
- $ref: '#/components/parameters/userGuid'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/MicrodepositsResponseBody'
post:
tags:
- microdeposits
operationId: createMicrodeposit
summary: Create or pre-initiate a microdeposit
description: "Use this endpoint to create or pre-initiate a microdeposit. The response will include the new microdeposit record with a status of `INITIATED` or `PREINITIATED` respectively.\n\nTo pre-initiate a microdeposit, you only need to set `email` (string), `first_name` (string), and `last_name` (string) in the request body. \n\nPre-initiating a microdeposit allows you to pass the end user's first name, last name, and email if this data has already been collected. If the end user selects an institution which requires the microdeposit flow, the pre-initiated `micro_deposit` will be used and the Connect Widget step that normally requests this info from the end user will be skipped. However, if the end user selects an institution which supports IAV, the pre-initiated `micro_deposit` will be deleted and IAV will be used instead. When requesting a Connect Widget URL after pre-initiating, make sure to set the `current_microdeposit_guid` to the resulting microdeposit's `guid` and set the `mode` to `verification`. If you use this enhanced flow, a `micro_deposit` should be pre-initiated for all connect sessions in verification mode. After pre-initiating a microdeposit, pass the GUID to the config as `current_microdeposit_guid` and set the `mode` to `verification` when requesting a Connect URL. Pre-initiating a microdeposit is optional. If you choose to implement this flow, it should be used for all Connect Widget sessions in verification mode.\n"
parameters:
- $ref: '#/components/parameters/userGuid'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/MicrodepositRequestBody'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/MicrodepositResponseBody'
/users/{user_guid}/micro_deposits/{micro_deposit_guid}:
parameters:
- $ref: '#/components/parameters/microDepositGuid'
- $ref: '#/components/parameters/userGuid'
delete:
tags:
- microdeposits
operationId: deleteMicrodeposit
summary: Delete a microdeposit
description: Use this endpoint to delete the specified microdeposit.
responses:
'204':
description: No Content
get:
tags:
- microdeposits
operationId: readUserMicrodeposit
summary: Read a microdeposit for a user
description: Use this endpoint to read the attributes of a specific microdeposit according to its unique GUID. <br></br> Webhooks for microdeposit status changes are triggered when a status changes. The actual status of the microdeposit guid updates every minute. You may force a status update by calling the read microdeposit endpoint.
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/MicrodepositResponseBody'
/micro_deposits/{micro_deposit_guid}/verify:
put:
tags:
- microdeposits
operationId: verifyMicrodeposit
summary: Verify a Microdeposit
description: Use this endpoint to verify the amounts deposited into the account during a microdeposit verification. The verification has not successfully completed until the `status` is `VERIFIED`. Poll the `/users/{user_guid}/micro_deposits/{micro_deposit_guid}` (read microdeposit) endpoint until you see this status or an error state.
parameters:
- $ref: '#/components/parameters/microDepositGuid'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/MicrodepositVerifyRequestBody'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/MicrodepositResponseBody'
/users/{user_guid}/account_verifications:
get:
tags:
- microdeposits
operationId: listUserVerifications
summary: List all verifications for a user
description: 'This endpoint returns a list of the account verifications associated with the user, as well as the status of those verifications.
'
parameters:
- $ref: '#/components/parameters/userGuid'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/MicrodepositResponseBody'
components:
schemas:
MicrodepositResponseBody:
properties:
micro_deposit:
items:
allOf:
- $ref: '#/components/schemas/MicrodepositElements'
- $ref: '#/components/schemas/MicrodepositResponse'
type: object
MicrodepositVerifyRequest:
properties:
deposit_amount_1:
type: number
example: 0.09
deposit_amount_2:
type: number
example: 0.09
type: object
MicrodepositRequestBody:
properties:
micro_deposit:
$ref: '#/components/schemas/MicrodepositElements'
type: object
MicrodepositResponse:
properties:
error_message:
type: string
nullable: true
example: null
guid:
type: string
example: MIC-09ba578e-8448-4f7f-89e1-b62ff2517edb
institution_code:
example: mxbank
type: string
institution_name:
example: MX Bank
type: string
status:
example: INITIATED
type: string
updated_at:
example: '2023-06-01T19:18:06Z'
type: string
verified_at:
example: null
nullable: true
type: string
type: object
MicrodepositVerifyRequestBody:
properties:
micro_deposit:
$ref: '#/components/schemas/MicrodepositVerifyRequest'
type: object
PaginationResponse:
properties:
current_page:
example: 1
type: integer
per_page:
example: 25
type: integer
total_entries:
example: 1
type: integer
total_pages:
example: 1
type: integer
type: object
MicrodepositsResponseBody:
properties:
micro_deposits:
items:
$ref: '#/components/schemas/MicrodepositResponse'
type: array
pagination:
$ref: '#/components/schemas/PaginationResponse'
type: object
MicrodepositElements:
properties:
account_name:
example: My test account
type: string
account_number:
example: '3331261'
type: string
account_type:
example: CHECKING
type: string
email:
example: joshyboy2@example.com
type: string
first_name:
example: Joshy
type: string
last_name:
example: Grobanne
type: string
routing_number:
example: 091000019
type: string
required:
- account_number
- account_type
- routing_number
parameters:
userGuid:
description: The unique identifier for a `user`, beginning with the prefix `USR-`.
example: USR-fa7537f3-48aa-a683-a02a-b18940482f54
in: path
name: user_guid
required: true
schema:
type: string
microDepositGuid:
name: micro_deposit_guid
description: The unique identifier for the microdeposit. Defined by MX.
in: path
required: true
example: MIC-09ba578e-8448-4f7f-89e1-b62ff2517edb
schema:
type: string
securitySchemes:
bearerAuth:
type: http
scheme: bearer
basicAuth:
scheme: basic
type: http