# 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