Payouts and Payins

Payouts offer a way of paying out money to a consumer, directly to their bank account. It provides a standard API interface for issuing payouts across various payment processors and banks.

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

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

{
  "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

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

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

{
  "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

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

{
  "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

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":"[e-mail]",
          "phone": "[phone]",
          "receiver_id": "122222",
          "source_currency": "COP"
        }'

Response

{
  "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":"[e-mail]",
  "phone": "[phone]",
  "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_urlfield 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

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

{ 
  "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