POST
/
payoutRequests
curl --request POST \
  --url https://prod.api.palomma.com/v0/payoutRequests \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "reference": "<string>",
  "payoutTargetId": "<string>",
  "amount": 123,
  "sourceMerchantAccountId": "<string>"
}'
{
  "id": "01HPR8QBF5QKA313RPBSKYB7DS",
  "reference": "<string>",
  "customerId": "01HPR57X6QR5ZRKEEKBSDBW4RA",
  "customerDetails": {
    "reference": "<string>",
    "name": "Pepito Perez",
    "documentType": "cc",
    "documentNumber": "1037551022",
    "email": "pepito@gmail.com",
    "phoneNumber": "3013111111"
  },
  "payoutTargetId": "01HPR8S7YF43PV3QV16TZDC80P",
  "payoutTargetDetails": {
    "reference": "<string>",
    "description": "<string>",
    "type": "bankAccount"
  },
  "status": "processing",
  "statusMessage": "AUTHENTICATION_FAILED",
  "amount": 100000,
  "amountSent": 100000,
  "fee": 500,
  "sourceMerchantAccountId": "<string>",
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z"
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
payoutTargetId
string
required

Payout Target to send money to.

​
amount
number
required

Amount to be sent in COP. Must be greater than $1.000. The maxiumum is configured per merchant but defaults to $5.000.000. Contact us if you need to increase this limit.

​
reference
string

Reference sent in by merchant to identify Payout Request.

​
sourceMerchantAccountId
string

An optional account ID of the source merchant account for this Payout Request.

Response

200
application/json
Payout Request created successfully
​
id
string

Unique identifier for this Payout Request.

Example:

"01HPR8QBF5QKA313RPBSKYB7DS"

​
reference
string

Reference sent in by merchant to identify Payout Request.

​
customerId
string

Reference to customer who owns the Payout Target for which the Payout Request was created.

Example:

"01HPR57X6QR5ZRKEEKBSDBW4RA"

​
customerDetails
object

Details about the customer who owns the Payout Target for which the Payout Request was created.

​
payoutTargetId
string

Reference to the Payout Target for which the Payout Request was created.

Example:

"01HPR8S7YF43PV3QV16TZDC80P"

​
payoutTargetDetails
object

Details about the Payout Target for which the Payout Request was created.

​
status
enum<string>

Status of the Payout Request.

Available options:
processing,
approved,
cancelled
​
statusMessage
enum<string>

Additional detail on the status. Only present when status is "cancelled".

Available options:
AUTHENTICATION_FAILED,
CUSTOMER_CANCELLATION,
DECLINED_BY_BANK,
EXPIRED,
INVALID_ACCOUNT,
NOT_ENOUGH_FUNDS,
ERROR
​
amount
number

Amount to send to the customer’s Payout Target.

Example:

100000

​
amountSent
number

Amount sent by Payout Request. Starts at amount and changes to 0 if cancelled.

Example:

100000

​
fee
number

Fee charged for the transaction. This fee will be subtracted from amountCollected at settlement time.

Example:

500

​
sourceMerchantAccountId
string

Reference to Merchant Account. Safe to ignore if Merchant Accounts are not being used.

​
createdAt
string

ISO string indicating when the Payout Request was created.

​
updatedAt
string

ISO string indicating when the Payout Request was last updated.

StatusGet All Payout Request