SSO Oauth API Specifications

Token Exchange

Melio will make an http POST request to the TokenExchangeUrl with a payload consisting of the following properties in application/json or application/x-www-form-urlencoded encoding.
This follows the standard OAuth 2 access token request endpoint specification as can be found here .

Property	Required	Description	Samples
code	Yes	The token that was provided to melio's auth url
client_id	no	In case you are using an existing oauth implementation you can provide melio with a client_id that will be sent in all token exchange requests. If not predefined in configuration, the property will not be sent
client_secret	no	Like client_id, used for integrating existing oauth flows.
scope	no	Like client_id, used for integrating existing oauth flows.
grant_type	yes	Will always be "authorization_code"	authorization_code

Melio expects the response to return a 200 status with a application/json encoded payload and have at least an access_token property. It can optionally also include expiration and refreshToken properties.

Curl example:

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code&code=362ad374-735c-4f69-aa8e-bf384f8602de&client_id=melioPartnerIdInPartner&client_secret=secretGive"

Response:

{
	"expires_in": 900,
	"token_type": "Bearer",
	"access_token": "238beab2-b545-4fee-80fa-63f224bc56f6"
}

Account Information

Melio will make an http GET request to the AccountInfoUrl with a bearer token authorization header (with value Bearer <accessToken>)
The endpoint should return the company and user information connected to the token via a 200 status application/json response
If required data is not provided, Melio will return an error screen and post an authentication error message to the host application.
If CollectMissingAccountInfo is enabled Melio will present a screen to collect required data that is missing. (Missing user.id and user.email will always return an error)

The json response should have the following format:

Property	Required	Validations	Description
user	Yes	Object	User information
user.id	Yes	String	A string identifying the user on Partner's system. This should uniquely identify the user
user.email	Yes	String Valid email address	The user's email.
user.firstName	Yes*	StringMin length: 2 Max length: 100 Pattern:/^[a-zA-Z\s\-,.]*$	The first name of the user.
user.lastName	Yes*	StringMin length: 2 Max length: 100 Pattern:/^[a-zA-Z\s\-,.]*$	The last name of the user
user.phone	Yes*	String Numbers and -+(). Only. At least 9 numbers	The user's phone number. US phone number only.
user.dateOfBirth	Yes*	String ISO 8601 formatted date only (YYYY-MM-DD)User must be 18 or older and below 120
company	Yes	Object	Company information
company.id	Yes	String	A string identifying the business on Partner's app. Should uniquely identify the company
company.name	Yes*	String Min length: 3 Must have at least 2 alphanumeric characters (a-zA-Z0-9)	The name of the business
company.address	Yes*	Address object	The business' address
company.address.line1	Yes*	String Min length: 1 No PO box address are allowed	The street, including house number, of the address
company.address.line2	no	String	Additional instructions for address
company.address.city	Yes*	String Min length: 1	Business address city
company.address.state	Yes*	String Uppercase 2 letters as defined in ISO 3166-2 (I.E. NY for New York etc…)	Business address state
company.address.postalcode	Yes*	String Min length: 5 numbers Pattern: /^[0-9\-\s]*$/	Postal code
company.legalName	no**	String	Legal name of the business, I.E. the name the business is incorporated under (which can be different then the name it appears as while doing business)
company.legalAddress	Yes*	Address object	The business' legal address
company.legalAddress.line1	Yes*	String Min length: 1 No PO box address are allowed	The street, including house number, of the address
company.legalAddress.line2	no	String	Additional instructions for address
company.legalAddress.city	Yes*	String Min length: 1	Business address city
company.legalAddress.state	Yes*	String Uppercase 2 letters as defined in ISO 3166-2 (I.E. NY for New York etc…)	Business address state
company.legalAddress.postalcode	Yes*	String Min length: 5 numbers Pattern: /^[0-9\-\s]*$/	Postal code
company.businessType	no**	Enum	Possible values: partnership, sole-proprietorship, llc, corporation, trust, non-profit, municipality, ngo
company.taxInfo	no**	Object	Tax information of business
company.taxInfo.type	no**	enum	Possible values: SSN, ITIN, EIN If tax type is SSN or ITIN, then businessType can be only trust or sole-proprietorship
company.taxInfo.identifier	no**	String Min length: 9 (excluding -)	If tax type is ITIN, identifier must start with the digit 9
company.industry.naicsCode	no*	Number Min: 10, max: 999,999	2, 4 or 6 digit NAICS code of the company's industry.
company.industry.name	no*	String	Industry description as provided by NAICS, if code isn't provided, industry name as provided by the user.

* user will need to fill these in the Melio web application if not provided by the partner
** user will need to fill these in the Melio web application before completing a payment if not provided by the partner

Curl example:

curl https://api.partnerapi.com/melio/account-info \
   -H "Accept: application/json" \
   -H "Authorization: Bearer 238beab2-b545-4fee-80fa-63f224bc56f6"

Response:

{
	"user": {
		"id": "us142664",
		"email": "jhon.doe@gmail.com",
		"firstName": "Jhon",
		"lastName": "Doe"
	},
	"company": {
		"id": "ac51512",
		"name": "Doe flowers and doves",
		"legalName": "Jhon doe flowers Inc",
		"phoneNumber": "(555) 656-1234",
		"address": {
			"state": "WI",
			"line1": "1330 Commonwealth Dr",
			"city": "Fort Atkinson",
			"postalCode": "535381366"
		},
		"taxInfo": {
			"identifier": "123123123",
			"type": "SSN"
		},
		"businessType": "sole-proprietorship"
	}
}

Available Funding Sources

If a FundingSourcesUrl is configured Melio will attempt to retrieved available funding sources for the organization during SSO and pre-populate them for the user to choose from.
Melio will make an http GET request to the FundingSourcesUrl with a bearer token authorization header (with value Bearer <accessToken>)
The endpoint should return the funding source information connected to the token via a 200 status application/json response
The json response should have the following format:

Property	Required	Validations	Description
fundingSources	Yes	Array	Funding sources information
fundingSources.id	Yes	String	A string identifying the fundingSource on Partner's app. Should uniquely identify a funding source
fundingSource.type	Yes	Enum	Possible values: ach
fundingSource.nickname	No	String Min length: 2 Max length: 40	Nickname user gave for this funding source
fundingSource.bankAccountNumber	Yes	string	Bank account number for funding source
fundingSource.bankRoutingNumber	Yes	string	Bank's routing number for the funding source
fundingSource.accountNumberLast4Digits	no	String Length: 4	Last 4 digits of bank account number. (Some banks provide virtual account numbers which don't match what the user is familiar with). If not provided will be derived from bankAccountNumber

Curl example:

curl https://api.partnerapi.com/melio/funding-sources \
   -H "Accept: application/json" \
   -H "Authorization: Bearer 238beab2-b545-4fee-80fa-63f224bc56f6"

Response:

{
	"fundingSources": [
		{
			"id": "ach412j2",
			"type": "ach",
			"nickName": "My prime account",
			"bankAccountNumber": "123123123",
			"bankRoutingNumber": "123123123"
		}
	]
}

Melio will add any funding source it finds to the list of available funding sources the user can make, if a previous funding source is no longer on the list (matched via the Id property) it'll be removed from the funding sources available for the user.