> For the complete documentation index, see [llms.txt](https://partner.doc.bunq.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://partner.doc.bunq.com/documentation/bunq-as-a-service/chapter-5-payments.md).
# Chapter 5: Payments
## Create Payment
> Create a new payment from a monetary account to another IBAN.\
> \
> \*\*IBAN Payment Features:\*\*\
> \- For Users belonging to Partners, only internal transfers are allowed between User <> Partner Monetary Accounts\
> \- For Partners with PSD2 access, external transfers to any IBAN are allowed\
> \- Description limited to 140 characters\
> \- Optional merchant reference for tracking
```json
{"openapi":"3.1.0","info":{"title":"bunq Partner API","version":"1.0.0"},"tags":[{"name":"Payment Management","description":"Send and manage payments between accounts"}],"servers":[{"url":"https://partner-api.sandbox.bunq.com","description":"Sandbox Partner API Server"},{"url":"https://api.partner.bunq.com","description":"Production Partner API Server"}],"security":[{"SessionAuth":[]},{"ClientSignature":[]}],"components":{"securitySchemes":{"SessionAuth":{"type":"apiKey","in":"header","name":"X-Bunq-Client-Authentication","description":"Session token received from POST /session-server"},"ClientSignature":{"type":"apiKey","in":"header","name":"X-Bunq-Client-Signature","description":"HMAC-SHA256 signature of request body using private key"}},"parameters":{"CacheControl":{"name":"Cache-Control","in":"header","required":false,"schema":{"type":"string","default":"no-cache"}},"UserAgent":{"name":"User-Agent","in":"header","required":false,"schema":{"type":"string"}},"BunqLanguage":{"name":"X-Bunq-Language","in":"header","required":false,"schema":{"type":"string","default":"en_US"}},"BunqRegion":{"name":"X-Bunq-Region","in":"header","required":false,"schema":{"type":"string","default":"NL"}},"BunqGeolocation":{"name":"X-Bunq-Geolocation","in":"header","required":false,"schema":{"type":"string"}},"BunqClientRequestId":{"name":"X-Bunq-Client-Request-Id","in":"header","required":false,"schema":{"type":"string"}},"BunqClientAuthentication":{"name":"X-Bunq-Client-Authentication","in":"header","required":true,"schema":{"type":"string","description":"Session token from POST /session-server"}},"BunqClientSignature":{"name":"X-Bunq-Client-Signature","in":"header","required":true,"schema":{"type":"string","description":"HMAC-SHA256 signature of request"}}}},"paths":{"/user/{userId}/monetary-account/{accountId}/payment":{"post":{"tags":["Payment Management"],"summary":"Create Payment","description":"Create a new payment from a monetary account to another IBAN.\n\n**IBAN Payment Features:**\n- For Users belonging to Partners, only internal transfers are allowed between User <> Partner Monetary Accounts\n- For Partners with PSD2 access, external transfers to any IBAN are allowed\n- Description limited to 140 characters\n- Optional merchant reference for tracking\n","parameters":[{"name":"userId","in":"path","required":true,"schema":{"type":"integer"}},{"name":"accountId","in":"path","required":true,"schema":{"type":"integer"}},{"$ref":"#/components/parameters/CacheControl"},{"$ref":"#/components/parameters/UserAgent"},{"$ref":"#/components/parameters/BunqLanguage"},{"$ref":"#/components/parameters/BunqRegion"},{"$ref":"#/components/parameters/BunqGeolocation"},{"$ref":"#/components/parameters/BunqClientRequestId"},{"$ref":"#/components/parameters/BunqClientAuthentication"},{"$ref":"#/components/parameters/BunqClientSignature"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["amount","counterparty_alias","description"],"properties":{"amount":{"type":"object","description":"Amount to transfer (must be positive and less than account balance)","required":["value","currency"],"properties":{"value":{"type":"string","description":"Amount in decimal format"},"currency":{"type":"string","description":"ISO 4217 currency code. Must be the same with the currency of the account, and the receiver account."}}},"counterparty_alias":{"type":"object","description":"IBAN details of the recipient","required":["type","value"],"properties":{"type":{"type":"string","enum":["IBAN"],"description":"Must be IBAN for external bank transfers"},"value":{"type":"string","description":"Valid IBAN of the recipient bank account. If transfer to another bunq user, IBAN of the MA still works."},"name":{"type":"string","description":"Name of the account holder."}}},"description":{"type":"string","description":"Payment description (maximum 140 characters for IBAN transfers)","maxLength":140},"merchant_reference":{"type":"string","description":"Optional merchant-specific reference for tracking","maxLength":35}}}}}},"responses":{"200":{"description":"Payment created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"Response":{"type":"array","items":{"type":"object","properties":{"Id":{"type":"object","properties":{"id":{"type":"integer","description":"Unique ID of the created payment"}}}}}}}}}}},"400":{"description":"Bad request - invalid parameters or insufficient funds","content":{"application/json":{"schema":{"type":"object","properties":{"Error":{"type":"array","items":{"type":"object","properties":{"error_description":{"type":"string"},"error_description_translated":{"type":"string"}}}}}}}}}}}}}}
```
## Get Payment Details
> Get detailed information about a specific payment.\
> \
> \*\*Includes:\*\*\
> \- Complete payment information\
> \- Counterparty details\
> \- Processing timestamps\
> \- Balance impact\
> \- Any attachments or references
```json
{"openapi":"3.1.0","info":{"title":"bunq Partner API","version":"1.0.0"},"tags":[{"name":"Payment Management","description":"Send and manage payments between accounts"}],"servers":[{"url":"https://partner-api.sandbox.bunq.com","description":"Sandbox Partner API Server"},{"url":"https://api.partner.bunq.com","description":"Production Partner API Server"}],"security":[{"SessionAuth":[]},{"ClientSignature":[]}],"components":{"securitySchemes":{"SessionAuth":{"type":"apiKey","in":"header","name":"X-Bunq-Client-Authentication","description":"Session token received from POST /session-server"},"ClientSignature":{"type":"apiKey","in":"header","name":"X-Bunq-Client-Signature","description":"HMAC-SHA256 signature of request body using private key"}},"parameters":{"CacheControl":{"name":"Cache-Control","in":"header","required":false,"schema":{"type":"string","default":"no-cache"}},"UserAgent":{"name":"User-Agent","in":"header","required":false,"schema":{"type":"string"}},"BunqLanguage":{"name":"X-Bunq-Language","in":"header","required":false,"schema":{"type":"string","default":"en_US"}},"BunqRegion":{"name":"X-Bunq-Region","in":"header","required":false,"schema":{"type":"string","default":"NL"}},"BunqGeolocation":{"name":"X-Bunq-Geolocation","in":"header","required":false,"schema":{"type":"string"}},"BunqClientRequestId":{"name":"X-Bunq-Client-Request-Id","in":"header","required":false,"schema":{"type":"string"}},"BunqClientAuthentication":{"name":"X-Bunq-Client-Authentication","in":"header","required":true,"schema":{"type":"string","description":"Session token from POST /session-server"}},"BunqClientSignature":{"name":"X-Bunq-Client-Signature","in":"header","required":true,"schema":{"type":"string","description":"HMAC-SHA256 signature of request"}}}},"paths":{"/user/{userId}/monetary-account/{accountId}/payment/{paymentId}":{"get":{"tags":["Payment Management"],"summary":"Get Payment Details","description":"Get detailed information about a specific payment.\n\n**Includes:**\n- Complete payment information\n- Counterparty details\n- Processing timestamps\n- Balance impact\n- Any attachments or references\n","parameters":[{"name":"userId","in":"path","required":true,"schema":{"type":"integer"}},{"name":"accountId","in":"path","required":true,"schema":{"type":"integer"}},{"name":"paymentId","in":"path","required":true,"schema":{"type":"integer"}},{"$ref":"#/components/parameters/CacheControl"},{"$ref":"#/components/parameters/UserAgent"},{"$ref":"#/components/parameters/BunqLanguage"},{"$ref":"#/components/parameters/BunqRegion"},{"$ref":"#/components/parameters/BunqGeolocation"},{"$ref":"#/components/parameters/BunqClientRequestId"},{"$ref":"#/components/parameters/BunqClientAuthentication"},{"$ref":"#/components/parameters/BunqClientSignature"}],"responses":{"200":{"description":"Detailed payment information","content":{"application/json":{"schema":{"type":"object","properties":{"Response":{"type":"array","items":{"type":"object","properties":{"Payment":{"type":"object","properties":{"id":{"type":"integer"},"created":{"type":"string","format":"date-time"},"updated":{"type":"string","format":"date-time"},"monetary_account_id":{"type":"integer"},"amount":{"type":"object","properties":{"value":{"type":"string"},"currency":{"type":"string"}}},"description":{"type":"string"},"type":{"type":"string"},"sub_type":{"type":"string"},"status":{"type":"string"},"counterparty_alias":{"type":"object","description":"Complete counterparty information","properties":{"iban":{"type":"string"},"name":{"type":"string"},"country":{"type":"string"}}},"merchant_reference":{"type":"string","description":"Optional merchant reference provided"},"balance_after_mutation":{"type":"object","description":"Account balance after this payment","properties":{"value":{"type":"string"},"currency":{"type":"string"}}},"geolocation":{"type":"object","description":"Location where payment was initiated","properties":{"latitude":{"type":"number"},"longitude":{"type":"number"},"altitude":{"type":"number"},"radius":{"type":"number"}}}}}}}}}}}}}}}}}}
```
## List Payments
> Get all payments (incoming and outgoing) for a specific monetary account.\
> \
> \*\*Payment Types Returned:\*\*\
> \- Outgoing payments (negative amounts)\
> \- Incoming payments (positive amounts) \
> \- All payment methods: IBAN, bunq transfers, card payments, etc.
```json
{"openapi":"3.1.0","info":{"title":"bunq Partner API","version":"1.0.0"},"tags":[{"name":"Payment Management","description":"Send and manage payments between accounts"}],"servers":[{"url":"https://partner-api.sandbox.bunq.com","description":"Sandbox Partner API Server"},{"url":"https://api.partner.bunq.com","description":"Production Partner API Server"}],"security":[{"SessionAuth":[]},{"ClientSignature":[]}],"components":{"securitySchemes":{"SessionAuth":{"type":"apiKey","in":"header","name":"X-Bunq-Client-Authentication","description":"Session token received from POST /session-server"},"ClientSignature":{"type":"apiKey","in":"header","name":"X-Bunq-Client-Signature","description":"HMAC-SHA256 signature of request body using private key"}},"parameters":{"CacheControl":{"name":"Cache-Control","in":"header","required":false,"schema":{"type":"string","default":"no-cache"}},"UserAgent":{"name":"User-Agent","in":"header","required":false,"schema":{"type":"string"}},"BunqLanguage":{"name":"X-Bunq-Language","in":"header","required":false,"schema":{"type":"string","default":"en_US"}},"BunqRegion":{"name":"X-Bunq-Region","in":"header","required":false,"schema":{"type":"string","default":"NL"}},"BunqGeolocation":{"name":"X-Bunq-Geolocation","in":"header","required":false,"schema":{"type":"string"}},"BunqClientRequestId":{"name":"X-Bunq-Client-Request-Id","in":"header","required":false,"schema":{"type":"string"}},"BunqClientAuthentication":{"name":"X-Bunq-Client-Authentication","in":"header","required":true,"schema":{"type":"string","description":"Session token from POST /session-server"}},"BunqClientSignature":{"name":"X-Bunq-Client-Signature","in":"header","required":true,"schema":{"type":"string","description":"HMAC-SHA256 signature of request"}}},"schemas":{"Pagination":{"type":"object","properties":{"future_url":{"type":["string","null"],"description":"URL to poll for results newer than the current real-time window (useful for long-polling; null if not applicable)."},"newer_url":{"type":["string","null"],"description":"URL to fetch the next newer page relative to the current result set (null if at newest page)."},"older_url":{"type":["string","null"],"description":"URL to fetch an older page (null if none)."}}}}},"paths":{"/user/{userId}/monetary-account/{accountId}/payment":{"get":{"tags":["Payment Management"],"summary":"List Payments","description":"Get all payments (incoming and outgoing) for a specific monetary account.\n\n**Payment Types Returned:**\n- Outgoing payments (negative amounts)\n- Incoming payments (positive amounts) \n- All payment methods: IBAN, bunq transfers, card payments, etc.\n","parameters":[{"name":"userId","in":"path","required":true,"schema":{"type":"integer"}},{"name":"accountId","in":"path","required":true,"schema":{"type":"integer"}},{"$ref":"#/components/parameters/CacheControl"},{"$ref":"#/components/parameters/UserAgent"},{"$ref":"#/components/parameters/BunqLanguage"},{"$ref":"#/components/parameters/BunqRegion"},{"$ref":"#/components/parameters/BunqGeolocation"},{"$ref":"#/components/parameters/BunqClientRequestId"},{"$ref":"#/components/parameters/BunqClientAuthentication"},{"$ref":"#/components/parameters/BunqClientSignature"}],"responses":{"200":{"description":"List of payments for the account","content":{"application/json":{"schema":{"type":"object","properties":{"Response":{"type":"array","items":{"type":"object","properties":{"Payment":{"type":"object","properties":{"id":{"type":"integer"},"created":{"type":"string","format":"date-time"},"updated":{"type":"string","format":"date-time"},"monetary_account_id":{"type":"integer"},"amount":{"type":"object","properties":{"value":{"type":"string","description":"Negative for outgoing, positive for incoming"},"currency":{"type":"string"}}},"description":{"type":"string"},"type":{"type":"string","enum":["BUNQ","EBA_SCT","EBA_SDD","IDEAL","SWIFT","FIS"],"description":"Payment processing type:\n- `BUNQ`: bunq to bunq transfer\n- `EBA_SCT`: SEPA Credit Transfer (IBAN)\n- `EBA_SDD`: SEPA Direct Debit\n- `IDEAL`: iDEAL payment\n- `SWIFT`: SWIFT wire transfer\n- `FIS`: Card payment\n"},"sub_type":{"type":"string","enum":["PAYMENT","WITHDRAWAL","REVERSAL","REQUEST","BILLING","SCT","SDD","NLO"],"description":"SEPA Credit Transfer"},"status":{"type":"string","enum":["PENDING","SETTLED","REJECTED","CANCELLED"],"description":"Current payment status:\n- `PENDING`: Payment is being processed\n- `SETTLED`: Payment completed successfully\n- `REJECTED`: Payment was rejected by bank\n- `CANCELLED`: Payment was cancelled\n"},"counterparty_alias":{"type":"object","description":"Information about the other party","properties":{"iban":{"type":"string"},"name":{"type":"string"}}},"balance_after_mutation":{"type":"object","description":"Account balance after this payment","properties":{"value":{"type":"string"},"currency":{"type":"string"}}}}}}}},"Pagination":{"$ref":"#/components/schemas/Pagination"}}}}}}}}}}}
```