# Payouts and Payins ## Setup In order to use payouts, a **payment-profile** needs to be setup with **payment-processor** and **rail** details for each bank payment profile model #### Currently supported payment processors and rails * Payments Way * ach * Mono * ach * turbo * transfiya * Movii * transfiya ### Rails The rails object contains two important objects whose structure may depend on the specific rail: * `config` * `credentials` (all data in this field will be encrypted) The `name` field must correspond to a supported rail name #### Mono Mono provides it's own fallback processing, and the alternative rails are specified in the `config.fallback_routing` field. Request ```bash curl -X POST --location 'https://api.orangepill.cloud/v1/rails' \ --header 'x-api-key: API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "name": "turbo", "config": { "account_id": "my_acc_number", "fallback_routing": ["ach"] "base_url": "https://api.sandbox.cuentamono.com/v1" }, "credentials": { "authorization": "Bearer key_012345XY", }, "active": true, "deleted": false, "default": true }' ``` Response ```bash { "id": "67ea61d6b5bb3aea747961ac", "name": "turbo", "config": { "account_id": "my_acc_number", "fallback_routing": ["ach"] "base_url": "https://api.sandbox.cuentamono.com/v1" }, "credentials": { "authorization": "b34c88f6b6b0409855b5f3", }, "default": true, "active": true, "deleted": false } ``` #### Payments Way Request 
curl -X POST --location 'https://api.orangepill.cloud/v1/rails' \
--header 'x-api-key: API_KEY' \
--header 'Content-Type: application/json' \
--data '{
          "name": "ach",
          "config": {
            "bank_code": "1007",
            "base_url": "http://190.60.126.210:3001/CashOutService.svc",
          },
          "credentials": {
            "username": "MY_USER_NAME",
            "password": "my_password
          },
          "deleted": false,
          "default": false 
       }'
#### Transfiya - Movii Request ```bash curl -X POST --location 'https://api.orangepill.cloud/v1/rails' \ --header 'x-api-key: API_KEY' \ --header 'Content-Type: application/json' \ --data '{ { "name": "transfiya", "config": { "base_url": "https://movii-bridge-ehmrxbxhlq-uk.a.run.app" }, "credentials": { "api_key": "b91964bd18889d78789baaa1dc4d75719c23485c500d674ebcc408c11", "signer_handle": "wilkjSAEuhreanAsfeapjgeAUENGdseaBboFs", "wallet_handle": "$573990000001", "client_id": "278e40d46ce942347rf7ca4092fe23e255", "client_secret": "08664b0c9bfd06093234cb44062rd942aba6b740a467664d" }, "deleted": false, "default": true }' ``` ### Payment processors The payment processor `name` must correspond to a supported payment processor. The `rails` array contains the ids of rails linked to this payment processor. Request ```bash curl -X POST --location 'https://api.orangepill.cloud/v1/payment-processors' \ --header 'x-api-key: API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "name": "mono", "rails": ["67ea61d6b5bb3aea747961ac"], "default": true, "active": true, "deleted": false }' ``` Response ```bash { "id": "67ea6bc8b5bb3aea747961ad", "name": "mono", "default": true, "active": true, "deleted": false, "rails": [ { "id": "67ea61d6b5bb3aea747961ac", "name": "turbo", "config": { "account_id": "my_acc_number", "fallback_routing": ["ach"], "base_url": "https://api.sandbox.cuentamono.com/v1" }, "credentials": { "authorization": "b34c88f6b6b0409855b5f3", }, "default": true, "active": true, "deleted": false } ] } ``` ### Payment profiles Payment profiles are the top level payout setup category and can contain several `payment_processors` The field `failover` specifies the fail-over logic in case of a payout transaction failure, and it can contain one of these values: * RAIL - the next transaction will be tried with the same rail of a different payment processor * PAYMENT\_PROCESSOR - next transaction will be tried with the next rail of the same payment processor *note:* since Mono has it's own fail-over mechanism, this field can be set to null Request ```bash curl -X POST --location 'https://api.orangepill.cloud/v1/payment-profiles' \ --header 'x-api-key: API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "name": "MY_PROFILE", "payment_processors": ["67ea6bc8b5bb3aea747961ad"], "failover": "RAIL", "default": true, "active": true, "deleted": false, "type": "payout" }' ``` Response ```bash { "id": "67ea6f7ab5bb3aea747961ae", "name": "MY_PROFILE", "failover": null, "default": "RAIL", "active": true, "deleted": false, "payment_processors": [ { "id": "67ea6bc8b5bb3aea747961ad", "name": "mono", "default": true, "active": true, "deleted": false, "rails": [ { "id": "67ea61d6b5bb3aea747961ac", "name": "turbo", "config": { "account_id": "my_acc_number", "fallback_routing": ["ach"] }, "credentials": { "authorization": "b34c88f6b6b0409855b5f3", "base_url": "https://api.sandbox.cuentamono.com/v1" }, "default": true, "deleted": false } ] } ] } ] ``` ## Payout The payout API has a common interface for all payment processors and rails. The payout will be sent using the payment profile specified in the `payment_profile` field. If this field is not specified, the payout will be sent with the *default* **payment profile** (which will use the *default* **payment processor** with the *default* **rail).** Request ```bash curl -X POST --location 'https://api.orangepill.cloud/v1/payout' \ --header 'x-api-key: API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "country": "CO", "payment_profile": "67ea6f7ab5bb3aea747961ae", "account": "1234567", "bank": "051", "account_type": "savings_account", "amount": 50000, "notify_url": "http://my-server.com/webhook", "document": "8881235000", "document_type": "CC", "name": "orangepill user", "email":"orangepill_user+4@orangepill.cc", "phone": "+573201111501", "receiver_id": "122222", "source_currency": "COP" }' ``` Response ```bash { "id": "67ea7c7eb5bb3aea747961af", "payment_profile": "67ea6f7ab5bb3aea747961ae", "payment_processor": "mono", "rail": "ach", "bank": "051", "account": "1234567", "account_type": "savings_account", "amount": "50000", "source_currency": "COP", "notify_url": "http://my-server.com/webhook", "country": "CO", "document": "8881235000", "document_type": "CC", "external_id": "trn_02zVPwC62K0NoHV99Uyr3B", "status": "INIT", "status_description":"" "name": "orangepill user", "email":"orangepill_user+4@orangepill.cc", "phone": "+573201111501", "receiver_id": "122222", "created_at": 1743420542246, "updated_at": 1743420543365, "retries": [] } ``` The initial response represents the data structure of the sent payout. \ Subsequent data will be sent to the web hook specified in the `notify_url`field with the updated statuses ## Payin The payin API has a common interface for all payment processors and rails and is similar to the payout. The payin will be sent using the payment profile specified in the `payment_profile` field, or will use the default. \ Payins and Payouts must have different Payment Profiles, each specifying either:\ `"type":"payin"` or `"type":"payout"` \ They can, however, reference the same payment processors and rails #### Transfiya - Movii example Request ```bash curl -X POST --location 'https://api.orangepill.cloud/v1/payout' \ --header 'x-api-key: API_KEY' \ --header 'Content-Type: application/json' \ --data '{ "account": "$573051000002", "receiver_id": "wiFAcpfsuPyGSxyTMbnSkWVLGWfFKBboFs", "payment_profile": "687a2d53b96d3f93ce52e2f7", "amount": "10000", "currency": "COP", "additional_remark": "Test payin", "notify_url": "http://my-server.com/webhook" }' ``` Response ```bash { "id": "688c89d34cd874d3fc986159", "payment_profile": "687a2d53b96d3f93ce52e2f7", "payment_processor": "687a2d2bb96d3f93ce52e2f6", "rail": "687a2c5bb96d3f93ce52e2f5", "amount": "10000", "account": "$573051000002", "receiver_id": "wiFAcpfsuPyGSxyTMbnSkWVLGWfFKBboFs", "additional_remark": "Test payin", "currency": "COP", "status": "INIT", "external_id": "020JVeIvCc2dkazhv", "notify_url": "http://my-server.com/webhook", "created_at": 1754040787936, "updated_at": 1754040788514, "retries": [] } ``` ### Status list * INIT - payout initialized and sent to the payment processor * PROCESSING - payout is being processed * COMPLETED - payout transaction successfully completed * FAILED - payout transaction failed Additional information regarding failed statuses can be found in the `status_description` field --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.orangepill.cloud/orangepill-api/payouts-and-payins.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.