POST
/
payinRequests
curl --request POST \
  --url https://prod.api.palomma.com/v0/payinRequests \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "reference": "<string>",
  "payinSourceId": "<string>",
  "amount": 123,
  "targetMerchantAccountId": "<string>"
}'
{
  "id": "01HPR83V7JBNJTKT303NTY3YGA",
  "reference": "<string>",
  "customerId": "01HPR57X6QR5ZRKEEKBSDBW4RA",
  "customerDetails": {
    "reference": "<string>",
    "name": "Pepito Perez",
    "documentType": "cc",
    "documentNumber": "1037551022",
    "email": "pepito@gmail.com",
    "phoneNumber": "3013111111"
  },
  "payinSourceId": "01HPR7A40E44S0WDR189YXA8GH",
  "payinSourceDetails": {
    "reference": "<string>",
    "description": "<string>",
    "partialPayinsEnabled": true,
    "type": "bankAccount"
  },
  "status": "approved",
  "statusMessage": "AUTHENTICATION_FAILED",
  "amount": 100000,
  "amountCollected": 100000,
  "fee": 500,
  "targetMerchantAccountId": "<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
​
payinSourceId
string
required

ID indicating which Payment Source to debit from.

​
amount
number
required

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

​
reference
string

Reference sent in by merchant to identify Payin Request.

​
targetMerchantAccountId
string

An optional account ID of the target merchant account for this Payin Request.

Response

200
application/json
Payin Request created successfully
​
id
string

Unique identifier for this Payin Request.

Example:

"01HPR83V7JBNJTKT303NTY3YGA"

​
reference
string

Reference sent in by merchant to identify Payin Request.

​
customerId
string

Reference to customer who owns the Payin Source from which the Payin Request was created.

Example:

"01HPR57X6QR5ZRKEEKBSDBW4RA"

​
customerDetails
object

Details about the customer who owns the Payin Source from which the Payin Request was created.

​
payinSourceId
string

Reference to Payin Source from which the Payin Request was created.

Example:

"01HPR7A40E44S0WDR189YXA8GH"

​
payinSourceDetails
object

Details about the Payin Source from which the Payin Request was created.

​
status
enum<string>

Status of the Payin Request.

Available options:
processing,
approved,
partial,
cancelled
Example:

"approved"

​
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 collect from the customer’s Payin Source. Must be an integer.

Example:

100000

​
amountCollected
number

Amount collected by Payin Request. Starts at 0 and changes on status change to "approved" or "partial".

Example:

100000

​
fee
number

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

Example:

500

​
targetMerchantAccountId
string

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

​
createdAt
string

ISO string indicating when the payin request was created.

​
updatedAt
string

ISO string indicating when the payin request was last updated.

StatusGet All Payin Requests