Asynchronous API for submitting long-running operations and retrieving their results without blocking, complementing the synchronous Assembly API. OpenAPI 3.0.0, version 1.0.0, 3 documented paths, supporting OAuth2 client-credentials and basic authentication.
{"openapi":"3.0.0","info":{"title":"Asynchronous API","description":"This section covers all the Assembly asynchronous APIs.","version":"1.0.0","contact":{"email":"support@assemblypayments.com","url":"http://docs.assemblypayments.com/"}},"servers":[{"description":"SwaggerHub API Auto Mocking","url":"https://virtserver.swaggerhub.com/AssemblyPlatforms/assembly-async-api/1.0.0"},{"url":"https://test.tnq.api.assemblypay.com/","description":"Sandbox (AKA Pre-live) environment hosting asynchronous endpoints."},{"url":"https://tnq.api.assemblypay.com/","description":"Production environment hosting asynchronous endpoints."}],"x-explorer-enabled":false,"x-samples-languages":["curl","ruby","php","javascript","csharp","go"],"paths":{"/items/{id}/make_payment":{"patch":{"tags":["Item Actions"],"summary":"Make Payment","description":"This endpoint extends the original `make_payment` API endpoint to allow asynchronous processing. Clients may optionally supply a wait parameter to have the server wait up to 30 seconds for a response from internal business systems. If a response has been received in that time, it is returned immediately. Otherwise status information and links are returned. Calling the status link returns the item response if available, status information otherwise. Clients may also optionally supply a callback URL in URL-encoded format. The path parameters `{item}`, `{account}` and `{uuid}` are supported. If a callback is present, the system POSTs the internal business system response to it.","parameters":[{"name":"id","in":"path","description":"ID of item to apply payment to","required":true,"schema":{"type":"string"},"example":"7190770-1-2908"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/make_payment_requestBody"}}}},"responses":{"200":{"description":"Response body contains the item response received within the supplied wait time. Note that the HTTP response code will reflect the internal system response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/single_item"},"examples":{"response":{"value":{"items":{"id":"7190770-1-2908","name":"Item 7190770-1-2908","description":"Test Item 7190770-1-2908","custom_descriptor":null,"payout_descriptor":null,"created_at":"2020-05-11T10:26:49.660Z","updated_at":"2020-05-11T10:26:49.660Z","state":"pending","net_amount":102,"chargedback_amount":0,"refunded_amount":0,"released_amount":0,"seller_url":"","buyer_url":"","remaining_amount":102,"status":22000,"amount":102,"payment_type_id":2,"due_date":null,"requested_release_amount":0,"pending_release_amount":0,"dynamic_descriptor":null,"invoice_url":null,"deposit_reference":"100014012533386","buyer_fees":0,"seller_fees":0,"credit_card_fee":0,"direct_debit_fee":0,"paypal_fee":0,"promisepay_fee":1,"batch_state":null,"total_outstanding":102,"total_amount":102,"currency":"AUD","payment_method":"pending","buyer_name":"Neol Buyer","buyer_email":"neol_buyer719013950014@assemblypayments.com","buyer_country":"AUS","seller_name":"Assembly seller71718579","seller_email":"neol_seller71718579@assemblypayments.com","seller_country":"AUS","payment_credit_card_enabled":true,"payment_direct_debit_enabled":true,"tds_check_state":null,"related":{"buyers":"buyer-719013950014","sellers":"seller-71718579"},"links":{"self":"/items/7190770-1-2908/make_payment?account_id=725cc8c0-759b-0138-5d6d-0a58a9feac05","buyers":"/items/7190770-1-2908/buyers","sellers":"/items/7190770-1-2908/sellers","status":"/items/7190770-1-2908/status","fees":"/items/7190770-1-2908/fees","transactions":"/items/7190770-1-2908/transactions","batch_transactions":"/items/7190770-1-2908/batch_transactions","wire_details":"/items/7190770-1-2908/wire_details","bpay_details":"/items/7190770-1-2908/bpay_details","tds_checks":"/items/7190770-1-2908/tds_checks"}}}}}}}},"202":{"description":"Request accepted: Response contains status information and query/callback link.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/status"},"examples":{"response":{"value":{"last_updated":"2020-07-15T15:04:05Z","submission_count":0,"message":"request awaiting submission","links":{"status":"https://tnq.api.assemblypay.com/request/d749f28378554394adab0b2401380bc7/status","callbacks":"https://tnq.api.assemblypay.com/request/d749f28378554394adab0b2401380bc7/callbacks"}}}}}}},"400":{"description":"Missing or invalid item ID or account ID","content":{}},"401":{"description":"Invalid authentication header","content":{}},"409":{"description":"Duplicate request conflict","content":{}},"503":{"description":"The end point handling your request has received an interrupt or terminate signal. Please try again.","content":{}}}}},"/request/{request_id}/status":{"get":{"tags":["Requests"],"summary":"Get Request Status","description":"This API is applicable for asynchronous requests submitted to `make_payment` through `tnq.api.assemblypay.com`. It returns the item response if available or current status otherwise.","parameters":[{"name":"request_id","in":"path","description":"Assembly-generated unique ID for this request.","required":true,"schema":{"type":"string","format":"UUID"},"example":"100fd4a0-0538-11e6-b512-3e1d05defe78"}],"responses":{"200":{"description":"Item response received from internal systems. Note that the HTTP response code will reflect the internal system response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/single_item"},"examples":{"response":{"value":{"items":{"id":"7190770-1-2908","name":"Item 7190770-1-2908","description":"Test Item 7190770-1-2908","custom_descriptor":null,"payout_descriptor":null,"created_at":"2020-05-11T10:26:49.660Z","updated_at":"2020-05-11T10:26:49.660Z","state":"pending","net_amount":102,"chargedback_amount":0,"refunded_amount":0,"released_amount":0,"seller_url":"","buyer_url":"","remaining_amount":102,"status":22000,"amount":102,"payment_type_id":2,"due_date":null,"requested_release_amount":0,"pending_release_amount":0,"dynamic_descriptor":null,"invoice_url":null,"deposit_reference":"100014012533386","buyer_fees":0,"seller_fees":0,"credit_card_fee":0,"direct_debit_fee":0,"paypal_fee":0,"promisepay_fee":1,"batch_state":null,"total_outstanding":102,"total_amount":102,"currency":"AUD","payment_method":"pending","buyer_name":"Neol Buyer","buyer_email":"neol_buyer719013950014@assemblypayments.com","buyer_country":"AUS","seller_name":"Assembly seller71718579","seller_email":"neol_seller71718579@assemblypayments.com","seller_country":"AUS","payment_credit_card_enabled":true,"payment_direct_debit_enabled":true,"tds_check_state":null,"related":{"buyers":"buyer-719013950014","sellers":"seller-71718579"},"links":{"self":"/items/7190770-1-2908/make_payment?account_id=725cc8c0-759b-0138-5d6d-0a58a9feac05","buyers":"/items/7190770-1-2908/buyers","sellers":"/items/7190770-1-2908/sellers","status":"/items/7190770-1-2908/status","fees":"/items/7190770-1-2908/fees","transactions":"/items/7190770-1-2908/transactions","batch_transactions":"/items/7190770-1-2908/batch_transactions","wire_details":"/items/7190770-1-2908/wire_details","bpay_details":"/items/7190770-1-2908/bpay_details","tds_checks":"/items/7190770-1-2908/tds_checks"}}}}}}}},"202":{"description":"Still awaiting item response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/status"},"examples":{"response":{"value":{"last_updated":"2020-07-15T15:04:37Z","submission_count":1,"message":"request awaiting response","links":{"status":"https://tnq.api.assemblypay.com/request/d749f28378554394adab0b2401380bc7/status","callbacks":"https://tnq.api.assemblypay.com/request/d749f28378554394adab0b2401380bc7/callbacks"}}}}}}},"401":{"description":"Invalid authentication header","content":{}},"503":{"description":"The end point handling your request has received an interrupt or terminate signal. Please try again.","content":{}}}}},"/request/{request_id}/callbacks":{"get":{"tags":["Requests"],"summary":"Get Request Callback Details","description":"This API is applicable for asynchronous requests submitted to `make_payment`. It returns information about callbacks executed upon receipt of a response to the associated request.","parameters":[{"name":"request_id","in":"path","required":true,"description":"Assembly-generated unique ID for this request.","schema":{"type":"string","format":"UUID"},"example":"100fd4a0-0538-11e6-b512-3e1d05defe78"}],"responses":{"200":{"description":"Callback execution details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/callbacks"},"examples":{"response":{"value":{"callbacks":[{"executed_utc":"2020-10-05T05:22:11Z","http_response":200,"detail":"{\"message\": \"hey thanks for the callback\"}"}],"links":{"status":"https://tnq.api.assemblypay.com/request/d749f28378554394adab0b2401380bc7/status","callbacks":"https://tnq.api.assemblypay.com/request/d749f28378554394adab0b2401380bc7/callbacks"}}}}}}},"401":{"description":"Invalid authentication header","content":{}},"503":{"description":"The end point handling your request has received an interrupt or terminate signal. Please try again.","content":{}}}}}},"components":{"parameters":{"offsetParam":{"name":"offset","in":"query","description":"Number of records to offset. Required for pagination.","required":false,"schema":{"type":"integer","minimum":0,"default":0}},"limitParam":{"name":"limit","in":"query","description":"Number of records to retrieve. Up to 200.","required":false,"schema":{"type":"integer","minimum":1,"maximum":200,"default":10}}},"schemas":{"single_item":{"type":"object","properties":{"items":{"$ref":"#/components/schemas/item"}}},"items":{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/item"}},"links":{"type":"object","properties":{"self":{"type":"string"}}},"meta":{"type":"object","properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"total":{"type":"integer"}}}}},"item":{"type":"object","properties":{"id":{"type":"string","example":"100fd4a0-0538-11e6-b512-3e1d05defe78"},"name":{"type":"string","example":"Landscaping Job #001"},"description":{"type":"string","example":"Planting of natives, removal of tree stump."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"state":{"type":"string","enum":["pending","payment_required","wire_pending","payment_pending","payment_held","payment_authorized","voided","fraud_hold","payment_deposited","work_completed","problem_flagged","problem_resolve_requested","problem_escalated","completed","cancelled","refunded","refund_pending","refund_flagged","off_platform_refunded","partial_completed","partial_paid","off_platform_chargedback"],"example":"pending"},"status":{"type":"integer","enum":[22000,22100,22110,22150,22175,22180,22195,22190,22200,22300,22400,22410,22420,22500,22575,22600,22610,22650,22670,22700,22800,22680],"example":22000},"amount":{"type":"integer","example":20000},"payment_type_id":{"type":"integer","example":2},"currency":{"type":"string","example":"AUD"},"buyer_name":{"type":"string","example":"Bella Buyer"},"buyer_email":{"type":"string","format":"email","example":"bella.buyer@assemblypayments.com"},"buyer_country":{"type":"string","example":"AUS"},"seller_name":{"type":"string","example":"Samuel Seller"},"seller_email":{"type":"string","format":"email","example":"samuel.seller@assemblypayments.com"},"seller_country":{"type":"string","format":"email","example":"AUS"},"tds_check_state":{"type":"string","format":"email","example":"NA"},"batch_state":{"type":"string","example":null},"invoice_url":{"type":"string","example":null},"payout_descriptor":{"type":"string","example":null},"remaining_amount":{"type":"integer","example":0},"requested_release_amount":{"type":"integer","example":0},"custom_descriptor":{"type":"string","example":null},"net_amount":{"type":"integer","example":20000},"chargedback_amount":{"type":"integer","example":0},"refunded_amount":{"type":"integer","example":0},"released_amount":{"type":"integer","example":0},"buyer_fees":{"type":"integer","example":0},"seller_fees":{"type":"integer","example":400},"credit_card_fee":{"type":"integer","example":0},"paypal_fee":{"type":"integer","example":0},"seller_url":{"type":"string"},"buyer_url":{"type":"string"},"direct_debit_fee":{"type":"integer","example":0},"due_date":{"type":"string","format":"date"},"pending_release_amount":{"type":"integer","example":0},"dynamic_descriptor":{"type":"string","example":null},"deposit_reference":{"type":"string","example":100014013961629},"promisepay_fee":{"type":"integer","example":350},"total_outstanding":{"type":"integer","example":20000},"total_amount":{"type":"integer","example":20000},"payment_method":{"type":"string","example":"pending"},"payment_credit_card_enabled":{"type":"boolean","example":true},"payment_direct_debit_enabled":{"type":"boolean","example":true},"related":{"type":"object","properties":{"buyers":{"type":"string","example":"064d6800-fff3-11e5-86aa-5e5517507c66"},"sellers":{"type":"string","example":"5830def0-ffe8-11e5-86aa-5e5517507c66"}}},"links":{"type":"object","properties":{"self":{"type":"string"},"buyers":{"type":"string"},"sellers":{"type":"string"},"status":{"type":"string"},"fees":{"type":"string"},"transactions":{"type":"string"},"batch_transactions":{"type":"string"},"wire_details":{"type":"string"},"bpay_details":{"type":"string"},"tds_checks":{"type":"string"}}}}},"links":{"type":"object","properties":{"status":{"type":"string","format":"URL","description":"Call this end point to retrieve the internal business response if received, or a status update otherwise.","example":"https://tnq.api.assemblypay.com/request/d749f28378554394adab0b2401380bc7/status"},"callbacks":{"type":"string","format":"URL","description":"Call this end point to retrieve callback tracking information. This property is only present if a callback was supplied with the original API invocation.","example":"https://tnq.api.assemblypay.com/request/d749f28378554394adab0b2401380bc7/callbacks"}}},"status":{"type":"object","properties":{"last_updated":{"type":"string","format":"DateTime RFC3339","example":"2020-07-15T15:04:05Z07:00"},"submission_count":{"type":"integer","example":0},"message":{"type":"string","example":"request awaiting submission"},"links":{"$ref":"#/components/schemas/links"}}},"callbacks":{"type":"object","properties":{"callbacks":{"type":"array","items":{"$ref":"#/components/schemas/callback"}},"links":{"$ref":"#/components/schemas/links"}}},"callback":{"type":"object","properties":{"executed_utc":{"type":"string","format":"date-time","example":"2020-10-05T05:22:11Z"},"http_response":{"type":"integer","example":200},"detail":{"type":"string","example":"{\"message\": \"hey thanks for the callback\"}"}}},"make_payment_requestBody":{"type":"object","required":["account_id"],"properties":{"account_id":{"description":"Account id of the bank account/credit card, etc making payment (not user id)","type":"string","example":"725cc8c0-759b-0138-5d6d-0a58a9feac05","default":"725cc8c0-759b-0138-5d6d-0a58a9feac05"},"device_id":{"description":"Device Information for the device initiating the payment. This must be provided for card payments.","type":"string","example":"358277090995038","default":"358277090995038"},"ip_address":{"description":"IP Information for the device initiating the payment. This must be provided for card payments.","type":"string","example":"49.192.154.141","default":"49.192.154.141"},"wait":{"description":"Time in seconds to wait for item response (up to 30). If this value is not provided, it will defaul to 0 and the call will go asynchronously.","type":"integer","example":"15","default":"15"},"callback":{"description":"Address to callback when an internal business system response is received. Path parameters {account} {item} and {uuid} may be used. The value must be URL-encoded. The example value shown here represents the URL https://callback.example.com/assembly/{item}/{account}/{uuid}","type":"string","example":"https%3A%2F%2Fcallback.example.com%2Fassembly%2F%7Bitem%7D%2F%7Baccount%7D%2F%7Buuid%7D","default":"https%3A%2F%2Fcallback.example.com%2Fassembly%2F%7Bitem%7D%2F%7Baccount%7D%2F%7Buuid%7D"}}}},"securitySchemes":{"basicAuth":{"type":"http","scheme":"basic"},"oAuth2ClientCredentials":{"type":"oauth2","description":"Please refer to Authentication section within https://developer.assemblypayments.com/reference#authentication","flows":{"clientCredentials":{"tokenUrl":"https://au-0000.sandbox.auth.assemblypay.com/tokens","scopes":{}}}}}},"security":[{"basicAuth":[]},{"oAuth2ClientCredentials":[]}],"x-proxy-enabled":true,"x-samples-enabled":true}