{ "swagger": "2.0", "info": { "title": "Ding API", "description": "The Ding API is a Level 0 REST web service.  We have used the swagger standard to describe this service. As a result, we are able to provide this interactive documentation page. For further information, you may view the additional documentation; read our FAQ or contact partnersupport@ding.com", "version": "V1" }, "host": "api.dingconnect.com", "schemes": [ "https" ], "paths": { "/api/V1/CancelTransfers": { "post": { "tags": [ "V1" ], "summary": "CancelTransfers", "description": "*Attempt to cancel transfers with the submitted TransferIds*\n\nThe agent should call `ListTransferRecords` with an appropriate query to \nget a list of `TransferIds` that are available to cancel.\n\nNot all transfers can be cancelled. This method will return the `ProcessingState` of the transfer: if the\nstate is \"Cancelled\", then the transfer was successfully cancelled and any appropriate balance compensations\nwill have been applied to the agent account. If the state is anything else, then the transfer could not be\ncancelled.\n\nPlease see the documentation section on [batching](/Api/Description#batching).", "operationId": "CancelTransfers", "consumes": [ "application/json" ], "produces": [ "application/json", "text/json" ], "parameters": [ { "in": "header", "name": "X-Correlation-Id", "description": "Correlates HTTP requests between a client and server", "type": "String" }, { "in": "body", "name": "cancellationRequests", "description": "An explicit list of records to cancel.", "required": true, "schema": { "type": "array", "items": { "$ref": "#/definitions/CancellationRequest" } } } ], "responses": { "400": { "description": "BadRequest", "schema": { "$ref": "#/definitions/IApiResponse" } }, "500": { "description": "InternalServerError", "schema": { "$ref": "#/definitions/IApiResponse" } }, "503": { "description": "ServiceUnavailable", "schema": { "$ref": "#/definitions/IApiResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/IApiResponse" } }, "200": { "description": "OK", "schema": { "$ref": "#/definitions/CancelTransfersResponse" } } } } }, "/api/V1/EstimatePrices": { "post": { "tags": [ "V1" ], "summary": "EstimatePrices", "description": "*Estimate prices for send or receive values*\n\nBefore a transfer is attempted, it is impossible to know the exact value that an account will receive due to fluctuating foreign exchange rates, provider promotions and fees.\nThis API call will attempt to estimate, from the current prices in the products list, what receive value will result from a given send value or vice versa.\n\nPlease see the documentation section on [batching](/Api/Description#batching).\n\n### Input parameters\nIn each input, `SendValue` and `ReceiveValue` cannot both be non-zero.\n\nIf `ReceiveValue` is non-zero we will attempt to estimate the price that the customer would need to *send* (in the agent currency) in order to receive the given `ReceiveValue`.\n\nIf `SendValue` is non-zero (and `SendCurrencyIso` is null or empty) we will attempt to estimate what the customer would *receive* for the given `SendValue` (and send value would be interpreted as a value expressed in the agent currency).\n\nIf `SendValue` is non-zero and `SendCurrencyIso` is specified, we will attempt to estimate what the customer would *receive* for the given `SendValue/SendCurrencyIso`. The agent\nshould contact Ding if he/she wishes to send in currencies other than the main currency of his/her account.", "operationId": "EstimatePrices", "consumes": [ "application/json" ], "produces": [ "application/json", "text/json" ], "parameters": [ { "in": "header", "name": "X-Correlation-Id", "description": "Correlates HTTP requests between a client and server", "type": "String" }, { "in": "body", "name": "requestedEstimations", "required": true, "schema": { "type": "array", "items": { "$ref": "#/definitions/EstimationRequest" } } } ], "responses": { "400": { "description": "BadRequest", "schema": { "$ref": "#/definitions/IApiResponse" } }, "500": { "description": "InternalServerError", "schema": { "$ref": "#/definitions/IApiResponse" } }, "503": { "description": "ServiceUnavailable", "schema": { "$ref": "#/definitions/IApiResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/IApiResponse" } }, "200": { "description": "OK", "schema": { "$ref": "#/definitions/EstimatePricesResponse" } } } } }, "/api/V1/GetAccountLookup": { "get": { "tags": [ "V1" ], "summary": "GetAccountLookup", "description": "*Get providers and product information for a specific account number*\n\nReturns country, provider and region code details for the account number. This information can be then be used as input parameters\nto `GetProducts`.\n\nPlease note, while `GetProducts` (and `GetProviders`) can also accept an `AccountNumber`, their behaviour when the system cannot match\nthe account number to a subset of products or providers is to return the entire list. This could be a problem for consuming\nsystems if the entire list of products or providers is very large.\n\n`GetAccountLookup` behaves differently - if no matching provider/region information can be found, it will return an empty list. \n\nIn most cases it will return a single entry, but it is possible to return mulitple items.", "operationId": "GetAccountLookup", "produces": [ "application/json", "text/json" ], "parameters": [ { "in": "query", "name": "accountNumber", "description": "For phone number based products, the account number should be in international phone number format.", "type": "string", "default": "" }, { "in": "header", "name": "X-Correlation-Id", "description": "Correlates HTTP requests between a client and server", "type": "String" } ], "responses": { "400": { "description": "BadRequest", "schema": { "$ref": "#/definitions/IApiResponse" } }, "500": { "description": "InternalServerError", "schema": { "$ref": "#/definitions/IApiResponse" } }, "503": { "description": "ServiceUnavailable", "schema": { "$ref": "#/definitions/IApiResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/IApiResponse" } }, "200": { "description": "OK", "schema": { "$ref": "#/definitions/GetAccountLookupResponse" } } } } }, "/api/V1/GetBalance": { "get": { "tags": [ "V1" ], "summary": "GetBalance", "description": "*Get the current agent balance*\n\nReturns the current agent balance. This will include any commission-on-sale increments, but will not reflect any\ntransfers that are currently processing. \n\nFor Instant transfers, the balance is decremented after a successful interaction with the product provider.\nFor Batch transfers, the balance is decremented immediately, and will be refunded later in case of failure.", "operationId": "GetBalance", "produces": [ "application/json", "text/json" ], "parameters": [ { "in": "header", "name": "X-Correlation-Id", "description": "Correlates HTTP requests between a client and server", "type": "String" } ], "responses": { "400": { "description": "BadRequest", "schema": { "$ref": "#/definitions/IApiResponse" } }, "500": { "description": "InternalServerError", "schema": { "$ref": "#/definitions/IApiResponse" } }, "503": { "description": "ServiceUnavailable", "schema": { "$ref": "#/definitions/IApiResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/IApiResponse" } }, "200": { "description": "OK", "schema": { "$ref": "#/definitions/GetBalanceResponse" } } } } }, "/api/V1/GetCountries": { "get": { "tags": [ "V1" ], "summary": "GetCountries", "description": "*Get a list of supported countries*\n\nRetrieves a list of standard two letter country codes that the system supports, along with the country name in English.\n\nPlease see the documentation section on [reference data](/Api/Description#reference-data).\n\nWe use ISO 3166-1 alpha-2 for our country codes, with the exception of XG used for products that are available for all countries.", "operationId": "GetCountries", "produces": [ "application/json", "text/json" ], "parameters": [ { "in": "header", "name": "X-Correlation-Id", "description": "Correlates HTTP requests between a client and server", "type": "String" } ], "responses": { "400": { "description": "BadRequest", "schema": { "$ref": "#/definitions/IApiResponse" } }, "500": { "description": "InternalServerError", "schema": { "$ref": "#/definitions/IApiResponse" } }, "503": { "description": "ServiceUnavailable", "schema": { "$ref": "#/definitions/IApiResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/IApiResponse" } }, "200": { "description": "OK", "schema": { "$ref": "#/definitions/GetCountriesResponse" } } } } }, "/api/V1/GetCurrencies": { "get": { "tags": [ "V1" ], "summary": "GetCurrencies", "description": "*Get a list of supported currencies*\n\nRetrieves a list of standard three letter currency codes that the system supports, along with the currency name in English.\n\nPlease see the documentation section on [reference data](/Api/Description#reference-data).\n\nWe use ISO 4217 for our currency codes.", "operationId": "GetCurrencies", "produces": [ "application/json", "text/json" ], "parameters": [ { "in": "header", "name": "X-Correlation-Id", "description": "Correlates HTTP requests between a client and server", "type": "String" } ], "responses": { "400": { "description": "BadRequest", "schema": { "$ref": "#/definitions/IApiResponse" } }, "500": { "description": "InternalServerError", "schema": { "$ref": "#/definitions/IApiResponse" } }, "503": { "description": "ServiceUnavailable", "schema": { "$ref": "#/definitions/IApiResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/IApiResponse" } }, "200": { "description": "OK", "schema": { "$ref": "#/definitions/GetCurrenciesResponse" } } } } }, "/api/V1/GetErrorCodeDescriptions": { "get": { "tags": [ "V1" ], "summary": "GetErrorCodeDescriptions", "description": "*Get a list of error code descriptions*\n\nEvery API response can contain one or more ErrorCodes that indicate why a request failed. This API can be used to \nget a list of human readable errors that correspond to those ErrorCodes. These error messages are aimed at the\nagent and are not suitable for display to the end user/customer.\n\nNote that we will not remove ErrorCodes, but we reserve the right to add new ones.\n\nPlease see the documentation section on [responses](/Api/Description#responses).", "operationId": "GetErrorCodeDescriptions", "produces": [ "application/json", "text/json" ], "parameters": [ { "in": "header", "name": "X-Correlation-Id", "description": "Correlates HTTP requests between a client and server", "type": "String" } ], "responses": { "400": { "description": "BadRequest", "schema": { "$ref": "#/definitions/IApiResponse" } }, "500": { "description": "InternalServerError", "schema": { "$ref": "#/definitions/IApiResponse" } }, "503": { "description": "ServiceUnavailable", "schema": { "$ref": "#/definitions/IApiResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/IApiResponse" } }, "200": { "description": "OK", "schema": { "$ref": "#/definitions/GetErrorCodeDescriptionsResponse" } } } } }, "/api/V1/GetProductDescriptions": { "get": { "tags": [ "V1" ], "summary": "GetProductDescriptions", "description": "*Get localized strings for products*\n\nPlease see the documentation section on [localization](/Api/Description#localization).\n\nPlease see the documentation section on [querying](/Api/Description#querying).", "operationId": "GetProductDescriptions", "produces": [ "application/json", "text/json" ], "parameters": [ { "in": "query", "name": "languageCodes", "description": "Filter the list to product descriptions with the submitted language codes.", "type": "array", "items": { "type": "string" }, "collectionFormat": "multi" }, { "in": "query", "name": "skuCodes", "description": "Filter the list to descriptions for products with the submitted SkuCodes.", "type": "array", "items": { "type": "string" }, "collectionFormat": "multi" }, { "in": "header", "name": "X-Correlation-Id", "description": "Correlates HTTP requests between a client and server", "type": "String" } ], "responses": { "400": { "description": "BadRequest", "schema": { "$ref": "#/definitions/IApiResponse" } }, "500": { "description": "InternalServerError", "schema": { "$ref": "#/definitions/IApiResponse" } }, "503": { "description": "ServiceUnavailable", "schema": { "$ref": "#/definitions/IApiResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/IApiResponse" } }, "200": { "description": "OK", "schema": { "$ref": "#/definitions/GetProductDescriptionsResponse" } } } } }, "/api/V1/GetProducts": { "get": { "tags": [ "V1" ], "summary": "GetProducts", "description": "*Get a list of products that can be used in SendTransfer*\n\nThis API returns a list of available products that satisfy request criteria.\n\nPlease see the documentation section on [querying](/Api/Description#querying).\n\n#### Localization\nProducts have localized descriptions and you should call `GetProductDescriptions` to get the appropriate\nlocalizations. See the section on [Localization](#localization) above.\n\n#### Setting Definitions\nSome providers require additional information to be submitted with transfer requests in the form of name-value\nsettings where the `Name` of the setting is defined by the provider and the `Value` is submitted with the request.\n\nIf a provider does require this, `SettingDefinitions` will be populated with the definition of those settings. The\n`Name` of each definition is used in transfer requests, and the Description will contain a hint as to what the\n`Value`s should contain. \n\nThe `Name` must be used verbatim (including casing and any special characters) in the SendTransfer request.\n\nThe `Description` is unformatted and non-localized so is not appropriate for any customer facing UI elements.\nThis field is informational and targeted at the API agent/integrator.\n\n#### Commission Rate\nThe rate of commission that will be applied for selling this product (if applicable).\n\n#### Processing Mode\nProducts can be processed in real-time (`ProcessingMode=Instant`), or some time in the future (`ProcessingMode=Batch`).\n\n* **Instant:** We will attempt to process the transfer immediately. The response from `SendTransfer` will \ncontain a transfer record whose `ProcessingState` is one of `Completed` or `Failed`.\n* **Batch:** We will process the transfer later. The response from `SendTransfer` will contain a transfer \nrecord with a `ProcessingState` of `Submitted`. The agent should use `ListTransferRecords` to periodically \ncheck the status of the transfer.\n\n#### Redemption Mechanism\nSome products require further intervention from the end-user or agent before their benefit is realized. For example, the user may\nneed to dial a number and enter a PIN that was returned in the receipt or the agent may need to complete other steps before the \nproduct can be sold. \n\nThis property can contain the following values:\n\n* **Immediate:** The transfer requires no further action from the customer, and will be received immediately.\n\n* **ReadReceipt:** Further instructions for how to complete the transfer will be printed within the `ReceiptText` property and the end user should\nfollow those instructions. For example: PIN based products, or Long Distance Minutes.\n\n* **ReadAdditionalInformation:** Further instructions for how to complete or use the transfer are in the `AdditionalInformation` property of the Product\nand the agent will need to code their application to follow those instructions. For example, a user may be required to submit their account number\nagainst one product (to \"register\" their phone number) before they may use other products\n\n#### Benefits\nEach product can convey a number of benefits on an account number, including account top up, data, bundles, sms, long distance credit, and so forth.\n\nCurrent benefits include the following: \n\n* Mobile\n* Minutes\n* Data\n* LongDistance\n* Electricity\n* TV\n* Internet\n* Utility\n* Balance\n\nThe benefit list will be extended in time. To make your system robust, we recommend you implement your integration so that it can handle any benefit type. \nAlternatively, you could routinely filter the product list to a list of benefits supported by your application.\n\n#### Validity Period\nSome transfers must be redeemed within a certain time-window by the user after purchase. `ValidityPeriodIso` communicates how long the user will\nhave to complete the transaction. For example, many PIN based products must be redeemed before the validity period elapses. \n\nWe use the ISO8601 duration format. For example, `P30D` is 30 days.\n\n#### UAT Number\nTransfers submitted using this number will be in test mode only. No balance will be deducted, but no\nprovider transaction will actually be performed. \n\n#### Additional Information \nFrom time to time we will try to offer completely new or non-standard products to existing agents that\ncan only be redeemed using non-standard mechanisms/procedures. We will use this field to communicate any\ninformation that we think will help the agent integrate. \n\nThis field is unformatted, not localized and unsuitable for end-user display.\n\n### Price Properties\n#### Agent and Customer Fees\nThe `CustomerFee` is the amount (in the agent currency) that the agent has asked us to collect from the customer. We will subtract this from the `SendValue` before passing to the provider. \n\nThe `DistributorFee` is the amount (in agent currency) that Ding charges the agent to fulfil the transfer. We will deduct this amount from the agent balance in addition to the `SendValue`. \n\nFor example, if\n- SendValue = 10\n- CustomerFee = 1\n- DistributorFee = 2\nThen\n- SendValue - CustomerFee (= 9) will be passed to the Provider, and \n- SendValue + DistributorFee (= 12) will be deducted from the agent balance\n\n#### Tax Calculation\nCountries around the world have different ways of quoting Tax values. `TaxCalculation` indicates how you should interpret the values in the other Tax fields. \n\nPossible values are:\n* Inclusive\n* Exclusive\n\nPlease see Tax Rates on Wikipedia for an explanation of the values.\n\nIf the `TaxCalculation` field is left blank, then tax is handled by the provider.", "operationId": "GetProducts", "produces": [ "application/json", "text/json" ], "parameters": [ { "in": "query", "name": "countryIsos", "description": "Filter the list to products for countries with the given ISOs.", "type": "array", "items": { "type": "string" }, "collectionFormat": "multi" }, { "in": "query", "name": "providerCodes", "description": "Filter the list to products supplied by providers with the submitted provider codes.", "type": "array", "items": { "type": "string" }, "collectionFormat": "multi" }, { "in": "query", "name": "skuCodes", "description": "Filter the list to products with the submitted SkuCodes.", "type": "array", "items": { "type": "string" }, "collectionFormat": "multi" }, { "in": "query", "name": "benefits", "description": "Filter the list to products with the listed benefits.", "type": "array", "items": { "type": "string" }, "collectionFormat": "multi" }, { "in": "query", "name": "regionCodes", "description": "Filter the list to products in regions with the submitted regionCodes.", "type": "array", "items": { "type": "string" }, "collectionFormat": "multi" }, { "in": "query", "name": "accountNumber", "description": "Filter the list to products that are valid for the submitted account number. For phone number based products, the account number should be in international phone number format.", "type": "string", "default": "" }, { "in": "header", "name": "X-Correlation-Id", "description": "Correlates HTTP requests between a client and server", "type": "String" } ], "responses": { "400": { "description": "BadRequest", "schema": { "$ref": "#/definitions/IApiResponse" } }, "500": { "description": "InternalServerError", "schema": { "$ref": "#/definitions/IApiResponse" } }, "503": { "description": "ServiceUnavailable", "schema": { "$ref": "#/definitions/IApiResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/IApiResponse" } }, "200": { "description": "OK", "schema": { "$ref": "#/definitions/GetProductsResponse" } } } } }, "/api/V1/GetPromotionDescriptions": { "get": { "tags": [ "V1" ], "summary": "GetPromotionDescriptions", "description": "*Get localized strings for promotions*\n\nPlease see the documentation section on [localization](/Api/Description#localization).\n\nPlease see the documentation section on [querying](/Api/Description#querying).\n\n#### Dates\nIt is not always possible to express when a promotion is available using the `ValidityPeriodIso`.\nFor example, a promotion may run for a two week period, but only be applicable on specific dates within that period.\n\nIn this case the `Dates` property of the localization description will contain a localized string describing the applicable\ndates separated by semicolons. Blank means 'ongoing'. For example - \"07/02/2017;07/03/2017;07/04/2017\".\n\n#### Bonus validity\nEach bonus has a validity period in days where the bonus will be applicable.\n\n#### Bonus type\nEach bonus has a type associated, the list of possible values is defined below, nevertheless there might be new types that are not included in the list.\n\nCurrent bonus types include the following:\n|Type|Description|\n|---|---|\n|+| Addition of the send amount |\n|%| Percentage of the send amount |\n|x| Multiplier of the send amount i.e. 2x is two times the original send amount |\n|MB| Megabytes |\n|GB| Gigabytes |\n|SMS| Number of sms |", "operationId": "GetPromotionDescriptions", "produces": [ "application/json", "text/json" ], "parameters": [ { "in": "query", "name": "languageCodes", "description": "Filter the list to promotion descriptions with the submitted language codes.", "type": "array", "items": { "type": "string" }, "collectionFormat": "multi" }, { "in": "header", "name": "X-Correlation-Id", "description": "Correlates HTTP requests between a client and server", "type": "String" } ], "responses": { "400": { "description": "BadRequest", "schema": { "$ref": "#/definitions/IApiResponse" } }, "500": { "description": "InternalServerError", "schema": { "$ref": "#/definitions/IApiResponse" } }, "503": { "description": "ServiceUnavailable", "schema": { "$ref": "#/definitions/IApiResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/IApiResponse" } }, "200": { "description": "OK", "schema": { "$ref": "#/definitions/GetPromotionDescriptionsResponse" } } } } }, "/api/V1/GetPromotions": { "get": { "tags": [ "V1" ], "summary": "GetPromotions", "description": "*Get a list of promotions*\n\nReturns a list promotions that may apply for the submitted criteria. \n\nPlease see the documentation section on [querying](/Api/Description#querying).\n\n#### Localization\nPromotions have localized descriptions and you should call `GetPromotionDescriptions` to get the appropriate\nlocalizations. See the section on Localization above.\n\n#### Validity Period\n`ValidityPeriodIso` is expressed in the ISO8601 duration format. EG `P30D` is 30 days.", "operationId": "GetPromotions", "produces": [ "application/json", "text/json" ], "parameters": [ { "in": "query", "name": "countryIsos", "description": "Filter the list to promotions for countries with the given ISOs.", "type": "array", "items": { "type": "string" }, "collectionFormat": "multi" }, { "in": "query", "name": "providerCodes", "description": "Filter the list to promotions on products supplied by providers with the submitted provider codes.", "type": "array", "items": { "type": "string" }, "collectionFormat": "multi" }, { "in": "query", "name": "accountNumber", "description": "Filter the list to promotions on products that are valid for the submitted account number. For phone number based products, the account number should be in international phone number format.", "type": "string", "default": "" }, { "in": "header", "name": "X-Correlation-Id", "description": "Correlates HTTP requests between a client and server", "type": "String" } ], "responses": { "400": { "description": "BadRequest", "schema": { "$ref": "#/definitions/IApiResponse" } }, "500": { "description": "InternalServerError", "schema": { "$ref": "#/definitions/IApiResponse" } }, "503": { "description": "ServiceUnavailable", "schema": { "$ref": "#/definitions/IApiResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/IApiResponse" } }, "200": { "description": "OK", "schema": { "$ref": "#/definitions/GetPromotionsResponse" } } } } }, "/api/V1/GetProviders": { "get": { "tags": [ "V1" ], "summary": "GetProviders", "description": "*Get a list of product providers available to the agent*\n\nRetrieves the list of providers available to the agent.\n\nPlease see the documentation section on [querying](/Api/Description#querying).\n\n#### Name\nIn some cases the `Name` property may include a country name or code. For example: \"Airtel India\" or\n\"Vodafone UK\".\n\n#### Validation Regex\nWhen a transfer is attempted against products that a provider supplies, the first thing we will do is evaluate the \nsubmitted Account Number against the `ValidationRegex`. The regex may contain multiple \"alternates\" in its definition\nto cover all the products that the provider supplies, as a result an account number may pass the regex, but be invalid\nfor one product and valid for another.\n\nThe Ding system is .Net based and as a result we will use the Regex library from Microsoft. That library is reported to\nbe Perl 5 compatible. We make every effort to ensure that the regular expression constructs we use are cross-language\ncompatible and we use regex101 to test our regular expressions using the \"pcre\" \nsetting.\n\n#### Customer Care Number\nFor certain products like PINs, it may be necessary to include a customer care number of the provider on the receipt\nin order to handle customer care issues.\n\n#### Operator Logo\nIf available, the `LogoUrl` field will be populated with a link to the provider's logo. \nYou can provide the height, width, or both, of the logo by following the sample query \"?height=xxx&width=yyy\". It is advised that \nthe preferred dominant dimension is the only one specified, as the logo may add white space to fully fill both dimensions.\nA sample of a URL with height specified is: https://imagerepo.ding.com/logo/AI/IN.png?height=100", "operationId": "GetProviders", "produces": [ "application/json", "text/json" ], "parameters": [ { "in": "query", "name": "providerCodes", "description": "Filter the list to providers with the submitted provider codes.", "type": "array", "items": { "type": "string" }, "collectionFormat": "multi" }, { "in": "query", "name": "countryIsos", "description": "Filter the list to providers in countries with the submitted countryIso.", "type": "array", "items": { "type": "string" }, "collectionFormat": "multi" }, { "in": "query", "name": "regionCodes", "description": "Filter the list to providers in regions with the submitted regionCodes.", "type": "array", "items": { "type": "string" }, "collectionFormat": "multi" }, { "in": "query", "name": "accountNumber", "description": "Filter the list to providers that are valid for the submitted account number. For phone number based products, the account number should be in international phone number format.", "type": "string", "default": "" }, { "in": "header", "name": "X-Correlation-Id", "description": "Correlates HTTP requests between a client and server", "type": "String" } ], "responses": { "400": { "description": "BadRequest", "schema": { "$ref": "#/definitions/IApiResponse" } }, "500": { "description": "InternalServerError", "schema": { "$ref": "#/definitions/IApiResponse" } }, "503": { "description": "ServiceUnavailable", "schema": { "$ref": "#/definitions/IApiResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/IApiResponse" } }, "200": { "description": "OK", "schema": { "$ref": "#/definitions/GetProvidersResponse" } } } } }, "/api/V1/GetProviderStatus": { "get": { "tags": [ "V1" ], "summary": "GetProviderStatus", "description": "*Get the current status of product providers*\n\nProviders can be suspended or be in an error state. This API allows an agent to find out if it will be possible\nto send a transfer to a particular provider.\n\nPlease see the documentation section on [querying](/Api/Description#querying).\n\n#### Message\nThe `Message` property in the response is unformatted and non-localized text that gives further details of the \nstatus of an operator. This message is directed at the agent and is not suitable for end-user consumption.", "operationId": "GetProviderStatus", "produces": [ "application/json", "text/json" ], "parameters": [ { "in": "query", "name": "providerCodes", "description": "Filter the list to providers with the submitted provider codes.", "type": "array", "items": { "type": "string" }, "collectionFormat": "multi" }, { "in": "header", "name": "X-Correlation-Id", "description": "Correlates HTTP requests between a client and server", "type": "String" } ], "responses": { "400": { "description": "BadRequest", "schema": { "$ref": "#/definitions/IApiResponse" } }, "500": { "description": "InternalServerError", "schema": { "$ref": "#/definitions/IApiResponse" } }, "503": { "description": "ServiceUnavailable", "schema": { "$ref": "#/definitions/IApiResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/IApiResponse" } }, "200": { "description": "OK", "schema": { "$ref": "#/definitions/GetProviderStatusResponse" } } } } }, "/api/V1/GetRegions": { "get": { "tags": [ "V1" ], "summary": "GetRegions", "description": "*Get a list of regions on the system*\n\nRetrieves a list of regions used in the system. Each region includes a Region Code, Region Name and CountryIso.\n\nPlease see the documentation section on [reference data](/Api/Description#reference-data).", "operationId": "GetRegions", "produces": [ "application/json", "text/json" ], "parameters": [ { "in": "query", "name": "countryIsos", "description": "Filter the list to regions in countries with the submitted countryIso.", "type": "array", "items": { "type": "string" }, "collectionFormat": "multi" }, { "in": "header", "name": "X-Correlation-Id", "description": "Correlates HTTP requests between a client and server", "type": "String" } ], "responses": { "400": { "description": "BadRequest", "schema": { "$ref": "#/definitions/IApiResponse" } }, "500": { "description": "InternalServerError", "schema": { "$ref": "#/definitions/IApiResponse" } }, "503": { "description": "ServiceUnavailable", "schema": { "$ref": "#/definitions/IApiResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/IApiResponse" } }, "200": { "description": "OK", "schema": { "$ref": "#/definitions/GetRegionsResponse" } } } } }, "/api/V1/ListTransferRecords": { "post": { "tags": [ "V1" ], "summary": "ListTransferRecords", "description": "*Query transfers that were submitted to the system*\n\nListTransferRecords gives the ability to search the details of transfers that have been submitted to the system by\nthe agent. Note these transfers must not be older than 2 months.\n\nPlease see the documentation section on [paging](/Api/Description#paging).\n\nPlease see the documentation section on [querying](/Api/Description#querying).", "operationId": "ListTransferRecords", "consumes": [ "application/json" ], "produces": [ "application/json", "text/json" ], "parameters": [ { "in": "header", "name": "X-Correlation-Id", "description": "Correlates HTTP requests between a client and server", "type": "String" }, { "in": "body", "name": "request", "required": true, "schema": { "$ref": "#/definitions/ListTransferRecordsRequest" } } ], "responses": { "400": { "description": "BadRequest", "schema": { "$ref": "#/definitions/IApiResponse" } }, "500": { "description": "InternalServerError", "schema": { "$ref": "#/definitions/IApiResponse" } }, "503": { "description": "ServiceUnavailable", "schema": { "$ref": "#/definitions/IApiResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/IApiResponse" } }, "200": { "description": "OK", "schema": { "$ref": "#/definitions/ListTransferRecordsResponse" } } } } }, "/api/V1/LookupBills": { "post": { "tags": [ "V1" ], "summary": "LookupBills", "description": "*Search available bills*\n\n`LookupBills` should be called for any product where `LookupBillsRequired` true that will be required for this product when making the `SendTransfer` request, which will pay the Bill.", "operationId": "LookupBills", "consumes": [ "application/json" ], "produces": [ "application/json", "text/json" ], "parameters": [ { "in": "header", "name": "X-Correlation-Id", "description": "Correlates HTTP requests between a client and server", "type": "String" }, { "in": "body", "name": "request", "required": true, "schema": { "$ref": "#/definitions/LookupBillsRequest" } } ], "responses": { "400": { "description": "BadRequest", "schema": { "$ref": "#/definitions/LookupBillsResponse" } }, "500": { "description": "InternalServerError", "schema": { "$ref": "#/definitions/LookupBillsResponse" } }, "503": { "description": "ServiceUnavailable", "schema": { "$ref": "#/definitions/LookupBillsResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/IApiResponse" } }, "200": { "description": "OK", "schema": { "$ref": "#/definitions/LookupBillsResponse" } } } } }, "/api/V1/SendTransfer": { "post": { "tags": [ "V1" ], "summary": "SendTransfer", "description": "*Send a transfer to an account*\n\nAn agent will construct a request that contains a product `SkuCode` and a `SendValue` that\nis between the Min and Max price (inclusive). The agent should also include a `DistributorRef` that \nuniquely identifies the transfer within their system.\n\nSendTransfer will respond with the transfer that was created - including a `TransferRef` that uniquely identifies the transfer within\nour system. There will also be information about the state of the transfer and the amount that was received.\n\nOn success, we will deduct the value of the transfer from the agent balance and apply any applicable commissions.\n\nThe SendTranfer method has a maximum proccessing time of 90 seconds. After 90 seconds, if the SendTransfer request is not completed, the system will return a response with `ProviderTimedOut`. \nThis transaction will be treated as a failed transaction and the balance will not be deducted. \n\n#### Sku Codes\nYou should only use `SkuCode` values returned by the `GetProducts` API call. No attempt should be made to guess or manufacture SkuCodes. \nProducts can be discontinued from time to time, and it is important that you keep up-to-date with the products available to your\naccount by regularly calling `GetProducts`. \n\n#### ValidateOnly\nWhen `ValidateOnly=true`, we will validate the request in our system to give an indication if a non validate transfer\nwould succeed with the submitted parameters. We will attempt to contact the product provider to see if the\nAccountNumber is valid in their system. However, not all providers have a mechanism to validate account numbers. In\nthis case the system can not indicate if the SendTransfer will fail in advance. \n\nThe agent balance will not be deducted during ValidateOnly, however the balance will be checked.\n\nWhen `ValidateOnly=true`, the `Price` in the response should be interpreted as an estimate only.\n\nWe will not assign a `TransferId` to the response when `ValidateOnly=true`\n\n#### Settings\nSome products declare `SettingDefintions` that mandate name-value pairs that can be submitted with the transfer and will be passed to\nthe Provider. \n\nAgents can submit their own name-value pairs and we will store them with the transfer. These name-value pairs\ncan be queried upon using the `ListTransferRecords` method.\n\n#### Processing State\n`ProcessingState` will indicate the current state of the transfer as it progresses through our system over time.\n\n- **Submitted**: The transfer was just submitted to the system and we have a record of it.\n- **Processing**: The system has started processing the request and we are in the act of fulfilling the transfer.\n- **Complete**: The transfer request is finished and it was successful.\n- **Failed**: The transfer request is finished, but there was some form of error.\n- **Cancelled**: The transfer request was cancelled.\n- **Cancelling**: A request to cancel the transfer has been sent to the provider.\n\n#### Receipts\nIn some cases there will be a `ReceiptText` in the response which will contain text that the product provider responded with, and this may\ncontain further instructions for the end user. \n\nSometimes the formatting of the ReceiptText returned by the provider is not acceptable, and an agent would like \nto use the values in their own template. For example in a HTML page, or on a space restricted device. `ReceiptParams` will contain \ninformation in name-value pairs that can be used to populate a template. The actual names will vary by provider and we will endeavour \nto supply all the right pairs. \n\nIf there is a PIN code available, 'ReceiptParams' will contain the key 'pin' with it's associated value.\n\n`ReceiptParams` may contain other values related to the provider, if the provider supplies an identifier for the transaction it will be returned as 'providerRef' in `ReceiptParams`, otherwise ‘providerRef’ will not be returned.\n\nIn some cases, we do not control the receipt text returned by the provider, and from time to time they may alter\ntheir text. If this happens, a name-value pair that previously existed in ReceiptParams dictionary may \ndisappear or a new one may pop up. Your application should be robust to these kind of changes.\n\n#### Deferred SendTransfer\nDeferred SendTransfer is a special type of SendTransfer that gives you the ability to get notified with HTTP callback (aka webhook) when the transfer\nis completed. You will get an immediate response with ProcessingState=Submitted and the final transfer result will be sent as webhook notification. \n\nWhen there are failures the transfer will be retried until it is completed successfully or the maximum retry threshold is reached and only then will a\nnotification be sent.\n\nMore information about Deferred SendTransfer can be found on our documentation page.", "operationId": "SendTransfer", "consumes": [ "application/json" ], "produces": [ "application/json", "text/json" ], "parameters": [ { "in": "header", "name": "X-Correlation-Id", "description": "Correlates HTTP requests between a client and server", "type": "String" }, { "in": "body", "name": "request", "required": true, "schema": { "$ref": "#/definitions/SendTransferRequest" } } ], "responses": { "400": { "description": "BadRequest", "schema": { "$ref": "#/definitions/SendTransferResponse" } }, "500": { "description": "InternalServerError", "schema": { "$ref": "#/definitions/SendTransferResponse" } }, "503": { "description": "ServiceUnavailable", "schema": { "$ref": "#/definitions/SendTransferResponse" } }, "401": { "description": "Unauthorized", "schema": { "$ref": "#/definitions/IApiResponse" } }, "200": { "description": "OK", "schema": { "$ref": "#/definitions/SendTransferResponse" } } } } } }, "definitions": { "AccountLookup": { "required": [ "ProviderCode", "RegionCode" ], "type": "object", "properties": { "ProviderCode": { "description": "ProviderCode of the account provided", "type": "string" }, "RegionCode": { "description": "RegioCode of the account provided", "type": "string" } }, "additionalProperties": false }, "Bill": { "required": [ "Price", "BillRef" ], "type": "object", "properties": { "Price": { "$ref": "#/definitions/Price" }, "BillRef": { "description": "Bill identifier to use as part of SendTransfer", "type": "string" }, "AdditionalInfo": { "description": "Name value pairs of data that is related to this Bill", "type": "object", "additionalProperties": { "type": "string" } } }, "additionalProperties": false }, "CancelTransfersResponse": { "required": [ "Items", "ResultCode", "ErrorCodes" ], "type": "object", "properties": { "Items": { "type": "array", "items": { "$ref": "#/definitions/TransferWithState" } }, "ResultCode": { "format": "int32", "type": "integer" }, "ErrorCodes": { "description": "", "type": "array", "items": { "$ref": "#/definitions/Error" } } }, "additionalProperties": false }, "CancellationRequest": { "required": [ "BatchItemRef", "TransferId" ], "type": "object", "properties": { "TransferId": { "$ref": "#/definitions/TransferId" }, "BatchItemRef": { "description": "A unique number for an item in an overall batched request", "type": "string" } }, "additionalProperties": false }, "Country": { "required": [ "CountryIso", "CountryName", "InternationalDialingInformation", "RegionCodes" ], "type": "object", "properties": { "CountryIso": { "description": "Alphabetic 2 character ISO country code", "type": "string" }, "CountryName": { "description": "English country name", "type": "string" }, "InternationalDialingInformation": { "description": "Phone number dialing information", "type": "array", "items": { "$ref": "#/definitions/InternationalDialingInfo" } }, "RegionCodes": { "description": "Regions supported within the country", "type": "array", "items": { "type": "string" } } }, "additionalProperties": false }, "Currency": { "required": [ "CurrencyIso", "CurrencyName" ], "type": "object", "properties": { "CurrencyIso": { "description": "Alphabetic 3 character ISO currency code", "type": "string" }, "CurrencyName": { "type": "string" } }, "additionalProperties": false }, "Error": { "required": [ "Code" ], "type": "object", "properties": { "Code": { "description": "The code that can be used to lookup the explanatory message associated with the error", "type": "string" }, "Context": { "description": "API specific context as to the reason for the specific code", "type": "string" } }, "additionalProperties": false }, "ErrorDescription": { "required": [ "Message", "Code" ], "type": "object", "properties": { "Message": { "description": "Error description", "type": "string" }, "Code": { "description": "The identifying error code that was returned in the response", "type": "string" } }, "additionalProperties": false }, "EstimatePricesResponse": { "required": [ "ResultCode", "ErrorCodes", "Items" ], "type": "object", "properties": { "ResultCode": { "format": "int32", "type": "integer" }, "ErrorCodes": { "type": "array", "items": { "$ref": "#/definitions/Error" } }, "Items": { "type": "array", "items": { "$ref": "#/definitions/EstimatedPrice" } } }, "additionalProperties": false }, "EstimatedPrice": { "required": [ "BatchItemRef", "ResultCode", "ErrorCodes" ], "type": "object", "properties": { "Price": { "$ref": "#/definitions/Price" }, "SkuCode": { "description": "The product SkuCode that we estimated for.", "type": "string" }, "BatchItemRef": { "description": "Refers to the unique reference of the item in the batch request", "type": "string" }, "ResultCode": { "format": "int32", "description": "The individual result code for processing the batch item with the given BatchItemRef.", "type": "integer" }, "ErrorCodes": { "description": "ErrorCodes (if any) for processing the batch item with the given BatchItemRef", "type": "array", "items": { "$ref": "#/definitions/Error" } } }, "additionalProperties": false }, "EstimationRequest": { "required": [ "BatchItemRef", "SkuCode" ], "type": "object", "properties": { "SendValue": { "format": "decimal", "description": "Desired send value", "type": "number" }, "SendCurrencyIso": { "description": "The currency of `SendValue`", "type": "string" }, "ReceiveValue": { "format": "decimal", "description": "Desired receive value", "type": "number" }, "SkuCode": { "description": "Product to estimate a price for", "type": "string" }, "BatchItemRef": { "description": "A unique reference for an item in a batched request.", "type": "string" } }, "additionalProperties": false }, "GetAccountLookupResponse": { "required": [ "Items", "ResultCode", "ErrorCodes" ], "type": "object", "properties": { "CountryIso": { "description": "The country of the account number", "type": "string" }, "AccountNumberNormalized": { "description": "We attempt to normalize phone numbers following the public telecommunication numbering plan E.164, if we succeed the normalized number will be returned in this field formatted as E164 without leading '+'", "type": "string" }, "Items": { "description": "This will contain provider information associated to the account number. If we can succesfully lookup the account number \nthe list will contain the info for products associated to it.", "type": "array", "items": { "$ref": "#/definitions/AccountLookup" } }, "ResultCode": { "format": "int32", "type": "integer" }, "ErrorCodes": { "type": "array", "items": { "$ref": "#/definitions/Error" } } }, "additionalProperties": false }, "GetBalanceResponse": { "required": [ "Balance", "CurrencyIso", "ResultCode", "ErrorCodes" ], "type": "object", "properties": { "Balance": { "format": "decimal", "description": "The distributor's balance", "type": "number" }, "CurrencyIso": { "type": "string" }, "ResultCode": { "format": "int32", "type": "integer" }, "ErrorCodes": { "type": "array", "items": { "$ref": "#/definitions/Error" } } }, "additionalProperties": false }, "GetCountriesResponse": { "required": [ "ResultCode", "ErrorCodes", "Items" ], "type": "object", "properties": { "ResultCode": { "format": "int32", "type": "integer" }, "ErrorCodes": { "type": "array", "items": { "$ref": "#/definitions/Error" } }, "Items": { "description": "The list of countries that our system is aware of.", "type": "array", "items": { "$ref": "#/definitions/Country" } } }, "additionalProperties": false }, "GetCurrenciesResponse": { "required": [ "ResultCode", "ErrorCodes", "Items" ], "type": "object", "properties": { "ResultCode": { "format": "int32", "type": "integer" }, "ErrorCodes": { "type": "array", "items": { "$ref": "#/definitions/Error" } }, "Items": { "type": "array", "items": { "$ref": "#/definitions/Currency" } } }, "additionalProperties": false }, "GetErrorCodeDescriptionsResponse": { "required": [ "ResultCode", "ErrorCodes", "Items" ], "type": "object", "properties": { "ResultCode": { "format": "int32", "type": "integer" }, "ErrorCodes": { "type": "array", "items": { "$ref": "#/definitions/Error" } }, "Items": { "description": "A list of ErrorCodes and their localized descriptions", "type": "array", "items": { "$ref": "#/definitions/ErrorDescription" } } }, "additionalProperties": false }, "GetProductDescriptionsResponse": { "required": [ "ResultCode", "ErrorCodes", "Items" ], "type": "object", "properties": { "ResultCode": { "format": "int32", "type": "integer" }, "ErrorCodes": { "type": "array", "items": { "$ref": "#/definitions/Error" } }, "Items": { "description": "A localized list of product descriptions.", "type": "array", "items": { "$ref": "#/definitions/LocalizedProductDescription" } } }, "additionalProperties": false }, "GetProductsResponse": { "required": [ "ResultCode", "ErrorCodes", "Items" ], "type": "object", "properties": { "ResultCode": { "format": "int32", "type": "integer" }, "ErrorCodes": { "type": "array", "items": { "$ref": "#/definitions/Error" } }, "Items": { "description": "A list of products that fulfil the submitted criteria.", "type": "array", "items": { "$ref": "#/definitions/Product" } } }, "additionalProperties": false }, "GetPromotionDescriptionsResponse": { "required": [ "ResultCode", "ErrorCodes", "Items" ], "type": "object", "properties": { "ResultCode": { "format": "int32", "type": "integer" }, "ErrorCodes": { "type": "array", "items": { "$ref": "#/definitions/Error" } }, "Items": { "description": "A localized list of promotions.", "type": "array", "items": { "$ref": "#/definitions/LocalizedPromotionDescription" } } }, "additionalProperties": false }, "GetPromotionsResponse": { "required": [ "ResultCode", "ErrorCodes", "Items" ], "type": "object", "properties": { "ResultCode": { "format": "int32", "type": "integer" }, "ErrorCodes": { "type": "array", "items": { "$ref": "#/definitions/Error" } }, "Items": { "description": "List of available promotions", "type": "array", "items": { "$ref": "#/definitions/Promotion" } } }, "additionalProperties": false }, "GetProviderStatusResponse": { "required": [ "ResultCode", "ErrorCodes", "Items" ], "type": "object", "properties": { "ResultCode": { "format": "int32", "type": "integer" }, "ErrorCodes": { "type": "array", "items": { "$ref": "#/definitions/Error" } }, "Items": { "type": "array", "items": { "$ref": "#/definitions/ProviderStatus" } } }, "additionalProperties": false }, "GetProvidersResponse": { "required": [ "ResultCode", "ErrorCodes", "Items" ], "type": "object", "properties": { "ResultCode": { "format": "int32", "type": "integer" }, "ErrorCodes": { "type": "array", "items": { "$ref": "#/definitions/Error" } }, "Items": { "description": "A list of providers that the distributor has Products for.", "type": "array", "items": { "$ref": "#/definitions/Provider" } } }, "additionalProperties": false }, "GetRegionsResponse": { "required": [ "ResultCode", "ErrorCodes", "Items" ], "type": "object", "properties": { "ResultCode": { "format": "int32", "type": "integer" }, "ErrorCodes": { "type": "array", "items": { "$ref": "#/definitions/Error" } }, "Items": { "description": "The list of regions that the system uses.", "type": "array", "items": { "$ref": "#/definitions/Region" } } }, "additionalProperties": false }, "IApiResponse": { "required": [ "ResultCode", "ErrorCodes" ], "type": "object", "properties": { "ResultCode": { "format": "int32", "type": "integer" }, "ErrorCodes": { "type": "array", "items": { "$ref": "#/definitions/Error" } } }, "additionalProperties": false }, "InternationalDialingInfo": { "required": [ "Prefix", "MinimumLength", "MaximumLength" ], "type": "object", "properties": { "Prefix": { "description": "The ITU International Subcriber Dialing prefix as defined in E.123 and E.164", "type": "string" }, "MinimumLength": { "format": "int32", "description": "The minimum length of a phone number, including the `Prefix`", "type": "integer" }, "MaximumLength": { "format": "int32", "description": "The maximum length of a phone number, including the `Prefix`", "type": "integer" } }, "additionalProperties": false }, "ListTransferRecordsRequest": { "required": [ "Take" ], "type": "object", "properties": { "TransferRef": { "description": "Filter by Ding TransferRef", "type": "string" }, "DistributorRef": { "description": "Filter transfers by DistributorRef.", "type": "string" }, "AccountNumber": { "description": "Filter transfers by AccountNumber", "type": "string" }, "Skip": { "format": "int32", "description": "The amount of records to by-pass before returning the remaining records", "type": "integer" }, "Take": { "format": "int32", "description": "The amount of records to return", "type": "integer" } }, "additionalProperties": false }, "ListTransferRecordsResponse": { "required": [ "ResultCode", "ErrorCodes", "Items", "ThereAreMoreItems" ], "type": "object", "properties": { "ResultCode": { "format": "int32", "type": "integer" }, "ErrorCodes": { "type": "array", "items": { "$ref": "#/definitions/Error" } }, "Items": { "description": "The list of items satisfying the transfer query.", "type": "array", "items": { "$ref": "#/definitions/TransferRecordWithErrorCodes" } }, "ThereAreMoreItems": { "description": "Indicates if the caller should execute the query again.", "type": "boolean" } }, "additionalProperties": false }, "LocalizedProductDescription": { "required": [ "DisplayText", "LocalizationKey", "LanguageCode" ], "type": "object", "properties": { "DisplayText": { "description": "A short description of the product.", "type": "string" }, "DescriptionMarkdown": { "description": "A longer description of the product.", "type": "string" }, "ReadMoreMarkdown": { "description": "More detailed infomation about the product.", "type": "string" }, "LocalizationKey": { "type": "string" }, "LanguageCode": { "type": "string" } }, "additionalProperties": false }, "LocalizedPromotionDescription": { "required": [ "Dates", "Headline", "TermsAndConditionsMarkDown", "BonusValidity", "PromotionType", "LocalizationKey", "LanguageCode", "SendAmounts" ], "type": "object", "properties": { "Dates": { "description": "Dates where the promotion is available within the ValidityPeriod", "type": "string" }, "Headline": { "description": "Short description of the promotion", "type": "string" }, "TermsAndConditionsMarkDown": { "description": "Terms and conditions of the promotion", "type": "string" }, "BonusValidity": { "description": "Different from ValidityPeriodIso as it has a non Iso value", "type": "string" }, "PromotionType": { "description": "Short description of the type of promotion", "type": "string" }, "LocalizationKey": { "type": "string" }, "LanguageCode": { "type": "string" }, "SendAmounts": { "description": "Amount ranges in distributor's currency where bonus are applicable", "type": "array", "items": { "$ref": "#/definitions/PromotionSendAmount" } } }, "additionalProperties": false }, "LookupBillsRequest": { "required": [ "AccountNumber", "SkuCode" ], "type": "object", "properties": { "SkuCode": { "description": "Code provided by GetProducts API", "type": "string" }, "AccountNumber": { "description": "The account number to target", "type": "string" }, "Settings": { "description": "Product specific name/value pairs to be associated with the lookup bills request", "type": "array", "items": { "$ref": "#/definitions/Setting" } } }, "additionalProperties": false }, "LookupBillsResponse": { "required": [ "Items", "ResultCode", "ErrorCodes" ], "type": "object", "properties": { "Items": { "type": "array", "items": { "$ref": "#/definitions/Bill" } }, "ResultCode": { "format": "int32", "type": "integer" }, "ErrorCodes": { "type": "array", "items": { "$ref": "#/definitions/Error" } } }, "additionalProperties": false }, "Price": { "required": [ "CustomerFee", "DistributorFee", "ReceiveValue", "ReceiveCurrencyIso", "ReceiveValueExcludingTax", "SendValue", "SendCurrencyIso" ], "type": "object", "properties": { "CustomerFee": { "format": "decimal", "description": "The fee that the distributor has asked us to collect from the customer", "type": "number" }, "DistributorFee": { "format": "decimal", "description": "The fee that Ding charges the distributor to fulfil the transfer", "type": "number" }, "ReceiveValue": { "format": "decimal", "description": "The estimated value that will be received by the target account, including any tax (if applicable).", "type": "number" }, "ReceiveCurrencyIso": { "description": "The currency of the ReceiveValue and ReceiveValueExcludingTax fields", "type": "string" }, "ReceiveValueExcludingTax": { "format": "decimal", "description": "The estimated amount received into the account before Tax was added", "type": "number" }, "TaxRate": { "format": "decimal", "description": "The tax rate that was applied", "type": "number" }, "TaxName": { "description": "The name of the tax applicable to this product", "type": "string" }, "TaxCalculation": { "description": "The type of calculation that was done (can vary by country)", "type": "string" }, "SendValue": { "format": "decimal", "description": "The value that is submitted to SendTransfer", "type": "number" }, "SendCurrencyIso": { "description": "The currency of the SendValue field", "type": "string" } }, "additionalProperties": false }, "Product": { "required": [ "ProviderCode", "SkuCode", "LocalizationKey", "SettingDefinitions", "Maximum", "Minimum", "CommissionRate", "ProcessingMode", "RedemptionMechanism", "Benefits", "UatNumber", "DefaultDisplayText", "RegionCode", "PaymentTypes" ], "type": "object", "properties": { "ProviderCode": { "description": "The provider of the product", "type": "string" }, "SkuCode": { "description": "Unique code to be used in conjunction with `SendTransfer` (SKU: \"Stock Keeping Unit\").", "type": "string" }, "LocalizationKey": { "description": "Key to be used in conjunction with `GetProductDescriptions`", "type": "string" }, "SettingDefinitions": { "description": "Name/Value pairs that should be submitted during `SendTransfer`", "type": "array", "items": { "$ref": "#/definitions/SettingDefinition" } }, "Maximum": { "$ref": "#/definitions/Price" }, "Minimum": { "$ref": "#/definitions/Price" }, "CommissionRate": { "format": "decimal", "description": "The rate of commission that will be applied for selling this product", "type": "number" }, "ProcessingMode": { "description": "Transaction processing mode for this product", "type": "string" }, "RedemptionMechanism": { "description": "Indicates if the customer is required to take further action in order to redeem the transfer", "type": "string" }, "Benefits": { "description": "What type of benefits will the transfer give to the target account", "type": "array", "items": { "type": "string" } }, "ValidityPeriodIso": { "description": "How long is the product valid for after purchase", "type": "string" }, "UatNumber": { "description": "User Acceptance Test Number", "type": "string" }, "AdditionalInformation": { "description": "Any distributor specific information/caveats about this particular product", "type": "string" }, "DefaultDisplayText": { "description": "The Display text from the `LocalizedProductDescription` in the default language (usually \"en\").", "type": "string" }, "RegionCode": { "description": "Region for this product", "type": "string" }, "PaymentTypes": { "description": "Indicates the supported payment types for this product. Current possible values are: Prepaid and Postpaid", "type": "array", "items": { "type": "string" } }, "LookupBillsRequired": { "description": "If true, it indicates to consume this product you must call LookupBills first and send the BillRef during the SendTransfer", "type": "boolean" } }, "additionalProperties": false }, "Promotion": { "required": [ "ProviderCode", "StartUtc", "EndUtc", "CurrencyIso", "MinimumSendAmount", "LocalizationKey" ], "type": "object", "properties": { "ProviderCode": { "description": "The code of the provider that the promotion applies to", "type": "string" }, "StartUtc": { "format": "date-time", "description": "Start date and time in UTC of the promotion", "type": "string" }, "EndUtc": { "format": "date-time", "description": "End date and time in UTC of the promotion. This will be DateTime.MaxValue if there is no end date.", "type": "string" }, "CurrencyIso": { "description": "Currency promotion - usually the same as the Provider", "type": "string" }, "ValidityPeriodIso": { "description": "Validity of the promotion", "type": "string" }, "MinimumSendAmount": { "format": "decimal", "description": "Minimum amount to be sent to apply for this promotion, specified in the distributor's currency", "type": "number" }, "LocalizationKey": { "description": "Key to be used in conjunction with `GetPromotionDescriptions`", "type": "string" } }, "additionalProperties": false }, "PromotionBonus": { "required": [ "BonusType", "Quantity", "Validity" ], "type": "object", "properties": { "BonusType": { "description": "What type of bonus will the promotion give", "type": "string" }, "Quantity": { "format": "decimal", "description": "Number of items for this bonus", "type": "number" }, "Validity": { "format": "int32", "description": "Bonus validity in days", "type": "integer" } }, "additionalProperties": false }, "PromotionSendAmount": { "required": [ "Minimum", "Maximum", "Bonuses" ], "type": "object", "properties": { "Minimum": { "format": "decimal", "description": "The minumum amount where bonus are applicable", "type": "number" }, "Maximum": { "format": "decimal", "description": "The maximum amount where bonus are applicable", "type": "number" }, "Bonuses": { "description": "List of applicable bonuses", "type": "array", "items": { "$ref": "#/definitions/PromotionBonus" } } }, "additionalProperties": false }, "Provider": { "required": [ "ProviderCode", "CountryIso", "Name", "ValidationRegex", "RegionCodes", "PaymentTypes" ], "type": "object", "properties": { "ProviderCode": { "description": "Uniquely identifies a provider", "type": "string" }, "CountryIso": { "description": "The country within which the provider operates", "type": "string" }, "Name": { "description": "The English trading name of the provider.", "type": "string" }, "ShortName": { "description": "A shorter version of the Name suitable for use in space restricted UI elements", "type": "string" }, "ValidationRegex": { "description": "Account numbers must match the ValidationRegex", "type": "string" }, "CustomerCareNumber": { "description": "Customer care number of the provider", "type": "string" }, "RegionCodes": { "description": "Regions supported by the provider within the country", "type": "array", "items": { "type": "string" } }, "PaymentTypes": { "description": "Indicates the supported payment types for all the products in this provider. Current possible values are: Prepaid and Postpaid", "type": "array", "items": { "type": "string" } }, "LogoUrl": { "description": "Link to image of the provider logo", "type": "string" } }, "additionalProperties": false }, "ProviderStatus": { "required": [ "ProviderCode", "IsProcessingTransfers" ], "type": "object", "properties": { "ProviderCode": { "description": "The unique provider code", "type": "string" }, "IsProcessingTransfers": { "description": "Indicates if the provider is processing transfers", "type": "boolean" }, "Message": { "description": "Details of operator status", "type": "string" } }, "additionalProperties": false }, "Region": { "required": [ "RegionCode", "RegionName", "CountryIso" ], "type": "object", "properties": { "RegionCode": { "description": "The region code", "type": "string" }, "RegionName": { "description": "The region name", "type": "string" }, "CountryIso": { "description": "The country ISO code of the region", "type": "string" } }, "additionalProperties": false }, "SendTransferRequest": { "required": [ "AccountNumber", "DistributorRef", "SendValue", "SkuCode", "ValidateOnly" ], "type": "object", "properties": { "SkuCode": { "description": "Code provided by GetProducts API", "type": "string" }, "SendValue": { "format": "decimal", "description": "The transfer value to be sent. Specified to two decimal places of accuracy of the major currency unit, e.g. 3.17 USD.", "type": "number" }, "SendCurrencyIso": { "description": "The currency of the `SendValue`. If this is null or empty, we will assume distributor currency.", "type": "string" }, "AccountNumber": { "description": "The account number to target", "type": "string" }, "DistributorRef": { "description": "Unique identifier in the distributor system to be associated with the transfer", "type": "string" }, "Settings": { "description": "Product specific name/value pairs to be associated with the transfer request", "type": "array", "items": { "$ref": "#/definitions/Setting" } }, "ValidateOnly": { "description": "Validate the request with the provider without doing a transfer", "type": "boolean" }, "BillRef": { "description": "Bill reference. Required when product has \"LookupBillsRequired\" set to true.", "type": "string" } }, "additionalProperties": false }, "SendTransferResponse": { "required": [ "ResultCode", "ErrorCodes" ], "type": "object", "properties": { "TransferRecord": { "$ref": "#/definitions/TransferRecord" }, "ResultCode": { "format": "int32", "type": "integer" }, "ErrorCodes": { "type": "array", "items": { "$ref": "#/definitions/Error" } } }, "additionalProperties": false }, "Setting": { "description": "A simple name/value pair", "required": [ "Name", "Value" ], "type": "object", "properties": { "Name": { "description": "The name of the setting as defined in the SettingDefinition", "type": "string" }, "Value": { "description": "The transfer specific value to associate with the Name", "type": "string" } }, "additionalProperties": false }, "SettingDefinition": { "required": [ "Name", "Description", "IsMandatory" ], "type": "object", "properties": { "Name": { "description": "Setting name to use during SendTranfer", "type": "string" }, "Description": { "description": "English explanation as to the purpose of the setting", "type": "string" }, "IsMandatory": { "description": "Indicates if the setting must be submitted during `SendTransfer`", "type": "boolean" } }, "additionalProperties": false }, "TransferId": { "required": [ "TransferRef", "DistributorRef" ], "type": "object", "properties": { "TransferRef": { "description": "The unique identifier for the transfer within our system", "type": "string" }, "DistributorRef": { "description": "The distributor's identifier for the transfer.", "type": "string" } }, "additionalProperties": false }, "TransferRecord": { "required": [ "SkuCode", "CommissionApplied", "ProcessingState", "AccountNumber" ], "type": "object", "properties": { "TransferId": { "$ref": "#/definitions/TransferId" }, "SkuCode": { "description": "The unique product SkuCode", "type": "string" }, "Price": { "$ref": "#/definitions/Price" }, "CommissionApplied": { "format": "decimal", "description": "The actual commision that was earned for selling this transfer", "type": "number" }, "StartedUtc": { "format": "date-time", "description": "The UTC datetime when processing the transfer was started.", "type": "string" }, "CompletedUtc": { "format": "date-time", "description": "The UTC datetime that the transfer was recorded as being completed in our system", "type": "string" }, "ProcessingState": { "description": "Will indicate the current state of the transfer as it progresses through our system", "type": "string" }, "ReceiptText": { "description": "Provider specific receipt text for the transfer. May contain additional information for the end customer.", "type": "string" }, "ReceiptParams": { "description": "Name value pairs of data that is in the ReceiptText along with other transactional details returned by the provider", "type": "object", "additionalProperties": { "type": "string" } }, "AccountNumber": { "description": "The account number targeted in the transfer", "type": "string" } }, "additionalProperties": false }, "TransferRecordWithErrorCodes": { "description": "Captures the TransferRecord that was created when a SendTransfer was submitted and any ErrorCodes that resulted", "required": [ "TransferRecord", "ResultCode", "ErrorCodes" ], "type": "object", "properties": { "TransferRecord": { "$ref": "#/definitions/TransferRecord" }, "ResultCode": { "format": "int32", "type": "integer" }, "ErrorCodes": { "description": "Any error codes that were returned as part of the SendTransfer or in the case of a Batch `ProcessingMode`\nthat may have occurred later after the batch was submitted to the Provider.", "type": "array", "items": { "$ref": "#/definitions/Error" } } }, "additionalProperties": false }, "TransferWithState": { "required": [ "TransferId", "ProcessingState", "BatchItemRef", "ResultCode", "ErrorCodes" ], "type": "object", "properties": { "TransferId": { "$ref": "#/definitions/TransferId" }, "ProcessingState": { "type": "string" }, "BatchItemRef": { "description": "Refers to the unique reference of the item in the batch request", "type": "string" }, "ResultCode": { "format": "int32", "description": "The individual result code for processing the batch item with the given BatchItemRef.", "type": "integer" }, "ErrorCodes": { "description": "ErrorCodes (if any) for processing the batch item with the given BatchItemRef", "type": "array", "items": { "$ref": "#/definitions/Error" } } }, "additionalProperties": false } }, "securityDefinitions": { "APIKeyHeader": { "type": "apiKey", "name": "api_key", "in": "header", "description": "Use the API key that was issued to you." } } }