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
headerrequired

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

Body

application/json
reference
string

Reference sent in by merchant to identify Payin Request.

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.

targetMerchantAccountId
string

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

Response

200 - application/json
id
string

Unique identifier for this Payin Request.

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.

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.

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
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.

amountCollected
number

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

fee
number

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

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