KulPayAPI reference
Partners
PSPs and billers (LSPs) as KulPay presents them on channels: their logos.
GET /logos/{id}
A partner's logo
The approved logo of a PSP or biller: a PNG with a transparent background, public (no key), for every channel to show. The biller catalogue gives its address as logo_url, with ?v=<version>: a new logo is a new URL, and a versioned request may be cached for good (Cache-Control: immutable). ETag and If-None-Match are supported.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
id required | path | string | The partner (PSP) id. |
v | query | string | The logo version. |
Responses
- 200 The logo.
- 304 Not modified.
- 404 No approved logo.
Request
curl -X GET "$KULPAY_URL/logos/{id}" \
-H "Authorization: Bearer $KULPAY_KEY"
404 Error text/plain
404 page not found
GET /v1/admin/psps/{id}/logo
A partner's logo, published or in review
?pending=1 returns the logo waiting for review. Requires accounts:read.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
id required | path | string | The partner (PSP) id. |
pending | query | string |
Responses
- 200 The logo.
- 404 None.
not_found
Request
curl -X GET "$KULPAY_URL/v1/admin/psps/{id}/logo" \
-H "Authorization: Bearer $KULPAY_KEY"
404 Error · not_found application/problem+json
{
"code": "not_found",
"detail": "no such logo",
"error": {
"code": "not_found",
"message": "no such logo"
},
"status": 404,
"title": "Not Found",
"type": "about:blank"
}
PUT /v1/admin/psps/{id}/logo
Publish a partner's logo
An operator publishes a logo at once (a partner uploads its own in the portal, for review). The body is the PNG: an alpha channel, transparent edges (all four corners and at least 90% of the border), 256 to 2048 px a side, aspect ratio 1:4 to 4:1, at most 1 MB. Anything else is refused with 400 invalid_logo saying what to fix. Requires accounts:write.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
id required | path | string | The partner (PSP) id. |
Request body image/png required
Responses
- 200 The logo state:
logo_status,logo_url,pending. - 400
invalid_logo. - 404 Unknown partner.
not_found
Request
curl -X PUT "$KULPAY_URL/v1/admin/psps/{id}/logo" \
-H "Authorization: Bearer $KULPAY_KEY"
200 Response application/json
{
"logo_note": null,
"logo_status": "approved",
"logo_url": "/logos/3KARihnYbNSj5SoAHKBQV7Bw0uO?v=3KWwi7owalkXqkSxnppSk2sKLoe",
"psp_id": "3KARihnYbNSj5SoAHKBQV7Bw0uO"
}
400 Error · invalid_logo application/problem+json
{
"code": "invalid_logo",
"detail": "the logo must have a transparent background: its corners are opaque",
"error": {
"code": "invalid_logo",
"message": "the logo must have a transparent background: its corners are opaque"
},
"status": 400,
"title": "Bad Request",
"type": "about:blank"
}
404 Error · not_found application/problem+json
{
"code": "not_found",
"detail": "no such partner or logo",
"error": {
"code": "not_found",
"message": "no such partner or logo"
},
"status": 404,
"title": "Not Found",
"type": "about:blank"
}
POST /v1/admin/psps/{id}/logo/review
Approve or reject a partner's logo
Approving publishes the logo waiting for review; rejecting needs a note saying why, and keeps the previously approved logo published. Requires accounts:write.
Parameters
| Name | In | Type | Description |
|---|---|---|---|
id required | path | string | The partner (PSP) id. |
Request body application/json required
| Field | Type | Description |
|---|---|---|
approve required | boolean | |
note | string |
Responses
- 200 The logo state.
- 400 Nothing to review, or a rejection without a note.
invalid_logo
Request
curl -X POST "$KULPAY_URL/v1/admin/psps/{id}/logo/review" \
-H "Authorization: Bearer $KULPAY_KEY" \
-H "Content-Type: application/json" \
-d '{
"approve": true,
"note": "Pagamento de energia, outubro"
}'
200 Response application/json
{
"logo_note": "The logo is cropped on the right; send the full mark with some margin.",
"logo_status": "rejected",
"logo_url": "/logos/3KARihnYbNSj5SoAHKBQV7Bw0uO?v=3KWwi7owalkXqkSxnppSk2sKLoe",
"psp_id": "3KARihnYbNSj5SoAHKBQV7Bw0uO"
}
400 Error · invalid_logo application/problem+json
{
"code": "invalid_logo",
"detail": "say why the logo is rejected, so the partner can fix it",
"error": {
"code": "invalid_logo",
"message": "say why the logo is rejected, so the partner can fix it"
},
"status": 400,
"title": "Bad Request",
"type": "about:blank"
}