Afinis Authorize to Pay API letting a buyer business provide bank account or virtual card details, purpose of payment, and authorization for a seller to debit the account.
{"swagger":"2.0","info":{"version":"1.0.6","title":"Debit Authorizations","description":"A buyer business wants to provide its bank account number or virtual card number, details on purpose of payment, and authorization for the supplier to debit the provided account number. The buyer wishes to receive a real time acknowledgement when the instructions have been received. ","contact":{"email":"info@afinis.org","url":"https://www.afinis.org"}},"host":"api.afinis.org","basePath":"/v1","securityDefinitions":{"APIKeyQueryParam":{"type":"apiKey","in":"query","name":"apikey"}},"consumes":["application/json"],"produces":["application/json"],"schemes":["https"],"paths":{"/debitauthorizations":{"post":{"description":"Allow paying an outstanding invoice by electronically providing account information and authorization securely to the payee to execute the payment and receive an acknowledgement that payer account will be debited on desired date.","operationId":"Authorize to Pay - Request","tags":["Authorize to Pay"],"consumes":["application/json"],"produces":["application/json"],"parameters":[{"name":"apiVersion","in":"header","required":true,"type":"string","format":"string"},{"in":"body","name":"Authorize to Debit","required":true,"description":"Pay an outstanding invoice electronically","schema":{"type":"object","required":["debtor","instructedAmount","pan","verification"],"properties":{"debtor":{"$ref":"#/definitions/party"},"endToEndIdentification":{"type":"string","minLength":1,"maxLength":35,"example":"CBA321"},"instructedAmount":{"$ref":"#/definitions/amount"},"requestedExecutionDate":{"type":"string","maxLength":10,"minLength":10,"example":"2019-03-01"},"remittanceInformation":{"$ref":"#/definitions/remittanceInformation"},"debtorAgent":{"$ref":"#/definitions/agent"},"debtorAccount":{"$ref":"#/definitions/account"},"verification":{"$ref":"#/definitions/verification"},"expiryDate":{"description":"ISOYearMonth - YYYY-MM","type":"string","minLength":7,"maxLength":7,"example":"2021-12"},"cardholder":{"$ref":"#/definitions/party"}}}}],"responses":{"201":{"description":"Created","schema":{"$ref":"#/definitions/response-201"}},"400":{"description":"Bad request","schema":{"$ref":"#/definitions/error-400"}},"401":{"description":"Unauthorized","schema":{"$ref":"#/definitions/error-401"}},"403":{"description":"Forbidden","schema":{"$ref":"#/definitions/error-403"}},"404":{"description":"Not Found","schema":{"$ref":"#/definitions/error-404"}},"405":{"description":"Method Not Allowed","schema":{"$ref":"#/definitions/error-405"}},"406":{"description":"Not Acceptable","schema":{"$ref":"#/definitions/error-406"}},"415":{"description":"Unsupported Media Type","schema":{"$ref":"#/definitions/error-415"}},"500":{"description":"Internal Server error","schema":{"$ref":"#/definitions/error-500"}},"503":{"description":"Service Unavailable","schema":{"$ref":"#/definitions/error-503"}}},"security":[{"APIKeyQueryParam":[]}]}}},"definitions":{"party":{"type":"object","properties":{"name":{"type":"string","maxLength":70,"example":"John Edison"},"postalAddress":{"$ref":"#/definitions/postalAddress"},"identification":{"type":"array","items":{"$ref":"#/definitions/identification"}},"phoneNumber":{"type":"string","maxLength":30,"example":"+1-302-515-5000"},"emailAddress":{"type":"string","maxLength":2048,"example":"zachary.eastwood@ABCcorp.com"}}},"agent":{"description":"Identification of a financial institution.","type":"object","required":["clearingSystemIdentification","memberIdentification"],"properties":{"clearingSystemIdentification":{"type":"string","example":"USABA","enum":["USABA"],"description":"Specification of a pre-agreed offering between clearing agents or the channel through which the payment instruction is processed: \n * `USABA` - Routing Transit number assigned by the ABA for US financial Institutions. \n"},"memberIdentification":{"type":"string","maxLength":35,"example":"061103852"}}},"account":{"description":"Unique and unambiguous identification for the account between the account owner and the account servicer.","type":"object","required":["identification","schemeName"],"properties":{"identification":{"type":"string","description":"Identification assigned by an institution","example":"12345678","minLength":1,"maxLength":17},"schemeName":{"type":"string","example":"DDA","enum":["DDA","Virtual Card"],"description":"Name of the identification scheme:\n * `DDA` - DDA \n * `Virtual Card` - Virtual Card \n"}}},"remittanceInformation":{"type":"object","properties":{"number":{"type":"string","minLength":1,"maxLength":35},"relatedDate":{"type":"string","maxLength":10,"minLength":10,"example":"2019-03-01"},"duePayableAmount":{"$ref":"#/definitions/amount"},"discountAppliedAmount":{"$ref":"#/definitions/amount"},"adjustmentAmountAndReason":{"type":"object","properties":{"amount":{"$ref":"#/definitions/amount"},"reason":{"type":"string","example":"CM","enum":["01","03","04","05","06","07","11","12","59","75","81","CM"],"description":"Name of the identification scheme:\n * `01` - Pricing Error \n * `03` - Extension Error \n * `04` - Item Not Accepted - Damaged \n * `05` - Item Not Accepted - Quality \n * `06` - Quantity Contested \n * `07` - Incorrect Product \n * `11` - Returns - Damage \n * `12` - Returns - Quality \n * `59` - Item not received \n * `75` - Total order not received \n * `81` - Credit as Agreed \n * `CM` - Covered by Credit Memo \n"},"additionalInformation":{"type":"string","minLength":1,"maxLength":140}}},"creditorReferenceInformation":{"$ref":"#/definitions/creditorReferenceInformation"}}},"verification":{"required":["authorizeToPay"],"type":"object","properties":{"authorizeToPay":{"type":"boolean","description":"Verification to specifically authorize the payment.","example":true},"type":{"type":"string","example":"CSCV","enum":["CSCV"],"description":"Name of the identification scheme:\n * `CSCV` - CSCVerification - Verification of Card Security Code \n"},"textValue":{"type":"string","description":"CVV code (3-4 characters) for virtual card","example":"643","minLength":1,"maxLength":4}}},"amount":{"required":["name","currency"],"type":"object","properties":{"amount":{"format":"float","example":1.01,"minLength":1},"currency":{"type":"string","example":"USD","maxLength":3,"minLength":3}}},"creditorReferenceInformation":{"type":"object","properties":{"type":{"type":"string","example":"PUOR","enum":["PUOR"],"description":"Name of the identification scheme:\n * `PUOR` - PurchaseOrder - Document is a purchase order \n"},"reference":{"type":"string","minLength":1,"maxLength":35}}},"identification":{"description":"Information that locates and identifies a specific address, as defined by postal services.","required":["identification"],"type":"object","properties":{"identification":{"description":"Identification assigned by an institution","type":"string","maxLength":35,"example":1234567891},"schemeName":{"type":"string","example":"CUST","enum":["DUNS","CUST"],"description":"Name of the identification scheme:\n * `DUNS` - Data Universal Numbering System - A unique identification number provided by Dun & Bradstreet to identify an organisation. \n * `CUST` - CustomerNumber, Number assigned by an issuer to identify a customer\n"}}},"postalAddress":{"description":"Information that locates and identifies a specific address, as defined by postal services.","type":"object","properties":{"streetName":{"description":"Name of a street or throughfare","type":"string","maxLength":70,"example":"Lexington Street"},"postCode":{"description":"Identifier consisting of a group of letters and/or numbers that is added to a postal address to assist the sorting of mail","type":"string","maxLength":11,"example":19801},"townName":{"description":"Name of a built-up area, with defined boundaries, and a local government","type":"string","maxLength":35,"example":"Wilmington"},"countrySubDivision":{"description":"Identifies a subdivision of a country such as state, region, county","type":"string","maxLength":35,"example":"DE"},"country":{"description":"Nation with its own government","type":"string","minLength":2,"maxLength":2,"example":"US"}}},"response-201":{"title":"Response 201 - Created","type":"object","description":"The request has succeeded and a new resource has been created as a result.","properties":{"status":{"type":"string","example":"Agree to debit","enum":["Agree to debit","Do not agree to debit"]},"requestedExecutionDate":{"type":"string","description":"Start date of the range","example":"2020-04-29","minLength":10,"maxLength":10},"creditor":{"$ref":"#/definitions/party"},"originalEndToEndIdentification":{"type":"string","maxLength":35,"example":"CBA321"}}},"error-400":{"title":"Error 400 - Bad Request","description":"The request could not be understood or required parameters were missing","type":"object","properties":{"detail":{"description":"error details","type":"array","items":{"$ref":"#/definitions/errorDetails-400"}}}},"errorDetails-400":{"title":"Error 400 - Bad Request - Details","type":"object","properties":{"errorCode":{"description":"A programmatic error code:\n * `2000` - Invalid JSON structure.\n * `2001` - '[Field name] is missing or invalid.'\n * `2002` - Invalid date.\n * `2003` - Invalid combination of fields submitted. Check the API specification for eligible combinations. \n * `2004` - '[Field name] cannot be more than [max number] characters.'\n","example":2000,"type":"number","enum":[2000,2001,2002,2003,2004]},"message":{"description":"A human readable description of the problem","example":"Invalid JSON structure.","type":"string"}}},"error-401":{"title":"Error 401 - Unauthorized","description":"Authentication failed or user doesn’t have permissions for requested operation","type":"object","properties":{"detail":{"description":"error details","type":"array","items":{"$ref":"#/definitions/errorDetails-401"}}}},"errorDetails-401":{"title":"Error 401 - Unauthorized - Details","type":"object","properties":{"errorCode":{"example":1000,"type":"number","enum":[1000,1001],"description":"A programmatic error code:\n * `1000` - API key is missing, invalid or expired. \n * `1001` - API token is invalid, expired, or account associated with key does not have access to that API.\n"},"message":{"description":"A human readable description of the problem","example":"API key is missing, invalid or expired.","type":"string"}},"required":["errorcode","message"]},"error-403":{"title":"Error 403 - Forbidden","description":"The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. Unlike 401, the client's identity is known to the server.","type":"object","required":["errorCode","message"],"properties":{"errorCode":{"example":403,"type":"number","enum":[403],"description":"A programmatic error code:\n * `403` - Forbidden\n"},"message":{"description":"A human readable description of the problem","example":"Forbidden","type":"string"}}},"error-404":{"title":"Error 404 - Not Found","description":"Resource was not found.","type":"object","required":["errorCode","message"],"properties":{"errorCode":{"example":404,"type":"number","enum":[404],"description":"A programmatic error code:\n * `404` - Resource was not found.\n"},"message":{"description":"A human readable description of the problem","example":"Resource was not found.","type":"string"}}},"error-405":{"title":"Error 405 - Method Not Allowed","description":"The request method is known by the server but has been disabled and cannot be used.","type":"object","required":["errorCode","message"],"properties":{"errorCode":{"example":405,"type":"number","enum":[405],"description":"A programmatic error code:\n * `405` - Method Not Allowed\n"},"message":{"description":"A human readable description of the problem","example":"Method Not Allowed","type":"string"}}},"error-406":{"title":"Error 406 - Not Acceptable","description":"Web server doesn't find any content that conforms to the criteria given by the user agent.","type":"object","required":["errorCode","message"],"properties":{"errorCode":{"example":406,"type":"number","enum":[406],"description":"A programmatic error code:\n * `406` - Not Acceptable\n"},"message":{"description":"A human readable description of the problem","example":"Not Acceptable","type":"string"}}},"error-415":{"title":"Error 415 - Unsupported Media Type","description":"The media format of the requested data is not supported by the server, so the server is rejecting the request.","type":"object","required":["errorCode","message"],"properties":{"errorCode":{"example":415,"type":"number","enum":[415],"description":"A programmatic error code:\n * `415` - Unsupported Media Type\n"},"message":{"description":"A human readable description of the problem","example":"Unsupported Media Type","type":"string"}}},"error-500":{"title":"Internal Server Error","description":"500 - Internal Server Error","type":"object","required":["details"],"properties":{"detail":{"description":"error details","type":"array","items":{"$ref":"#/definitions/internalServerErrorDetails"}}}},"internalServerErrorDetails":{"title":"Internal Server Error Details","type":"object","required":["errorCode","message"],"properties":{"errorCode":{"example":3001,"type":"number","enum":[3001],"description":"A programmatic error code:\n * `3001` - Internal Server error.\n"},"message":{"description":"A human readable description of the problem","example":"Internal Server error","type":"string"}}},"error-503":{"title":"Error 503 - Service Unavailable","description":"Service is temporarily unavailable","type":"object","required":["errorCode","message"],"properties":{"errorCode":{"example":503,"type":"number","enum":[503],"description":"A programmatic error code:\n * `503` - Service Unavailable\n"},"message":{"description":"A human readable description of the problem","example":"Service is temporarily unavailable.","type":"string"}}}}}