Return SWIFT payment

Return a payment

curl --request POST \
  --url https://api.pgw-sandbox.finventi.com/v3/payments/{id}/returns \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "additionalInfo": "<string>",
  "compensationAmount": 123,
  "taxAmount": 123
}
'

import requests

url = "https://api.pgw-sandbox.finventi.com/v3/payments/{id}/returns"

payload = {
    "additionalInfo": "<string>",
    "compensationAmount": 123,
    "taxAmount": 123
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Idempotency-Key': '<idempotency-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({additionalInfo: '<string>', compensationAmount: 123, taxAmount: 123})
};

fetch('https://api.pgw-sandbox.finventi.com/v3/payments/{id}/returns', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.pgw-sandbox.finventi.com/v3/payments/{id}/returns",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'additionalInfo' => '<string>',
    'compensationAmount' => 123,
    'taxAmount' => 123
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.pgw-sandbox.finventi.com/v3/payments/{id}/returns"

	payload := strings.NewReader("{\n  \"additionalInfo\": \"<string>\",\n  \"compensationAmount\": 123,\n  \"taxAmount\": 123\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.pgw-sandbox.finventi.com/v3/payments/{id}/returns")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"additionalInfo\": \"<string>\",\n  \"compensationAmount\": 123,\n  \"taxAmount\": 123\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.pgw-sandbox.finventi.com/v3/payments/{id}/returns")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"additionalInfo\": \"<string>\",\n  \"compensationAmount\": 123,\n  \"taxAmount\": 123\n}"

response = http.request(request)
puts response.read_body

{
  "createdAt": "2025-11-21T12:46:54.321667Z",
  "creditor": {
    "account": {
      "iban": "<string>",
      "other": {
        "id": "<string>",
        "issuer": "<string>",
        "scheme": {
          "code": "<string>",
          "proprietary": "<string>"
        }
      }
    },
    "agent": {
      "bic": "DEMOLT1XXXX",
      "name": "<string>"
    },
    "address": {
      "country": "LT",
      "line": "<string>",
      "structured": {
        "buildingName": "<string>",
        "buildingNumber": "<string>",
        "countrySubDivision": "<string>",
        "department": "<string>",
        "districtName": "<string>",
        "floor": "<string>",
        "postBox": "<string>",
        "postCode": "<string>",
        "room": "<string>",
        "street": "<string>",
        "subDepartment": "<string>",
        "townLocationName": "<string>"
      },
      "town": "Vilnius"
    },
    "name": "<string>",
    "organisationIdentification": {
      "otherIdentifications": [
        {
          "id": "<string>",
          "issuer": "<string>",
          "scheme": {
            "code": "<string>",
            "proprietary": "<string>"
          }
        }
      ],
      "bic": "<string>",
      "lei": "<string>"
    },
    "privateIdentification": {
      "otherIdentifications": [
        {
          "id": "<string>",
          "issuer": "<string>",
          "scheme": {
            "code": "<string>",
            "proprietary": "<string>"
          }
        }
      ],
      "birthInformation": {
        "city": "<string>",
        "country": "<string>",
        "date": "<string>",
        "province": "<string>"
      }
    }
  },
  "debtor": {
    "account": {
      "iban": "<string>",
      "other": {
        "id": "<string>",
        "issuer": "<string>",
        "scheme": {
          "code": "<string>",
          "proprietary": "<string>"
        }
      }
    },
    "agent": {
      "bic": "DEMOLT1XXXX",
      "name": "<string>"
    },
    "address": {
      "country": "LT",
      "line": "<string>",
      "structured": {
        "buildingName": "<string>",
        "buildingNumber": "<string>",
        "countrySubDivision": "<string>",
        "department": "<string>",
        "districtName": "<string>",
        "floor": "<string>",
        "postBox": "<string>",
        "postCode": "<string>",
        "room": "<string>",
        "street": "<string>",
        "subDepartment": "<string>",
        "townLocationName": "<string>"
      },
      "town": "Vilnius"
    },
    "name": "<string>",
    "organisationIdentification": {
      "otherIdentifications": [
        {
          "id": "<string>",
          "issuer": "<string>",
          "scheme": {
            "code": "<string>",
            "proprietary": "<string>"
          }
        }
      ],
      "bic": "<string>",
      "lei": "<string>"
    },
    "privateIdentification": {
      "otherIdentifications": [
        {
          "id": "<string>",
          "issuer": "<string>",
          "scheme": {
            "code": "<string>",
            "proprietary": "<string>"
          }
        }
      ],
      "birthInformation": {
        "city": "<string>",
        "country": "<string>",
        "date": "<string>",
        "province": "<string>"
      }
    }
  },
  "direction": "OUTBOUND",
  "endToEndId": "<string>",
  "id": 10300007,
  "instructedAmount": 100,
  "instructedCurrency": "EUR",
  "metadata": [
    "<string>"
  ],
  "scheme": "SEPA_CT",
  "sddActionOptions": [
    {
      "reasons": [
        {
          "available": true,
          "code": "MD06",
          "deadline": "2026-10-15T11:15:00+03:00"
        }
      ],
      "type": "RETURN",
      "deadline": "2026-08-27T11:15:00+03:00",
      "settlementDate": "2023-12-25",
      "windowEndDate": "2026-12-25"
    }
  ],
  "sddRejectWindowExpired": true,
  "sddReturnWindowsExpired": true,
  "settlementAmount": 100,
  "settlementCurrency": "EUR",
  "status": "COMPLETED",
  "type": "PAYMENT",
  "adjustmentDisplayParties": {
    "creditor": {
      "account": "<string>",
      "bic": "<string>",
      "name": "<string>"
    },
    "debtor": {
      "account": "<string>",
      "bic": "<string>",
      "name": "<string>"
    }
  },
  "categoryPurposeCode": "BONU",
  "categoryPurposeProprietary": "<string>",
  "chargesAndAdjustments": {
    "compensation": 25,
    "returnCharges": 50,
    "unaccountedTax": 123
  },
  "creditTransferType": "CUSTOMER",
  "directDebit": {
    "amendmentIndicator": true,
    "amendmentInformationDetails": {
      "originalCreditorSchemeId": "<string>",
      "originalDebtorAccount": "<string>",
      "originalMandateId": "<string>"
    },
    "esignature": "<string>",
    "mandateId": "MANDATE-2026-001",
    "sequenceType": "RCUR",
    "signatureDate": "2026-01-15"
  },
  "instructionId": "<string>",
  "messageId": "<string>",
  "originBic": "<string>",
  "originName": "<string>",
  "originReasonCode": "AC04",
  "originReasonInfo": "<string>",
  "parentPaymentId": 123,
  "parentTransactionAmount": 123,
  "purpose": "Invoice #12345",
  "purposeCode": "<string>",
  "settlementDate": "2023-12-25",
  "statusReason": {
    "code": "ACSC",
    "message": "Accepted settlement completed"
  },
  "structuredReference": {
    "issuer": "ISO",
    "reference": "RF123456"
  },
  "swift": {
    "businessMessageId": "BIZ-MSG-001",
    "charges": {
      "items": [
        {
          "amount": 50,
          "currency": "EUR",
          "bic": "<string>"
        }
      ],
      "bearer": "SHAR"
    },
    "messageDefinition": "pacs.008.001.08",
    "receiverBic": "<string>",
    "senderBic": "<string>",
    "settlementAccount": {
      "currency": "EUR",
      "iban": "<string>",
      "other": {
        "id": "<string>",
        "issuer": "<string>",
        "scheme": {
          "code": "<string>",
          "proprietary": "<string>"
        }
      }
    },
    "settlementMethod": "INDA",
    "uetr": "<string>"
  },
  "t2": {
    "priority": "HIGH",
    "uetr": "a1b2c3d4-1111-4222-8333-000000000001"
  },
  "ultimateCreditor": {
    "name": "<string>",
    "organisationIdentification": {
      "otherIdentifications": [
        {
          "id": "<string>",
          "issuer": "<string>",
          "scheme": {
            "code": "<string>",
            "proprietary": "<string>"
          }
        }
      ],
      "bic": "<string>",
      "lei": "<string>"
    },
    "privateIdentification": {
      "otherIdentifications": [
        {
          "id": "<string>",
          "issuer": "<string>",
          "scheme": {
            "code": "<string>",
            "proprietary": "<string>"
          }
        }
      ],
      "birthInformation": {
        "city": "<string>",
        "country": "<string>",
        "date": "<string>",
        "province": "<string>"
      }
    }
  },
  "ultimateDebtor": {
    "name": "<string>",
    "organisationIdentification": {
      "otherIdentifications": [
        {
          "id": "<string>",
          "issuer": "<string>",
          "scheme": {
            "code": "<string>",
            "proprietary": "<string>"
          }
        }
      ],
      "bic": "<string>",
      "lei": "<string>"
    },
    "privateIdentification": {
      "otherIdentifications": [
        {
          "id": "<string>",
          "issuer": "<string>",
          "scheme": {
            "code": "<string>",
            "proprietary": "<string>"
          }
        }
      ],
      "birthInformation": {
        "city": "<string>",
        "country": "<string>",
        "date": "<string>",
        "province": "<string>"
      }
    }
  },
  "updatedAt": "2025-11-21T12:46:54.612954Z"
}

{
  "code": "<string>",
  "data": {
    "errors": [
      {
        "code": "<string>",
        "field_name": "<string>",
        "message": "<string>",
        "value": "<string>"
      }
    ],
    "message": "<string>"
  },
  "message": "<string>"
}

{
  "code": "<string>",
  "data": {
    "errors": [
      {
        "code": "<string>",
        "field_name": "<string>",
        "message": "<string>",
        "value": "<string>"
      }
    ],
    "message": "<string>"
  },
  "message": "<string>"
}

{
  "code": "<string>",
  "data": {
    "errors": [
      {
        "code": "<string>",
        "field_name": "<string>",
        "message": "<string>",
        "value": "<string>"
      }
    ],
    "message": "<string>"
  },
  "message": "<string>"
}

{
  "code": "<string>",
  "data": {
    "errors": [
      {
        "code": "<string>",
        "field_name": "<string>",
        "message": "<string>",
        "value": "<string>"
      }
    ],
    "message": "<string>"
  },
  "message": "<string>"
}

POST

payments

{id}

returns

Return a payment

curl --request POST \
  --url https://api.pgw-sandbox.finventi.com/v3/payments/{id}/returns \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "additionalInfo": "<string>",
  "compensationAmount": 123,
  "taxAmount": 123
}
'

import requests

url = "https://api.pgw-sandbox.finventi.com/v3/payments/{id}/returns"

payload = {
    "additionalInfo": "<string>",
    "compensationAmount": 123,
    "taxAmount": 123
}
headers = {
    "Idempotency-Key": "<idempotency-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Idempotency-Key': '<idempotency-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({additionalInfo: '<string>', compensationAmount: 123, taxAmount: 123})
};

fetch('https://api.pgw-sandbox.finventi.com/v3/payments/{id}/returns', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.pgw-sandbox.finventi.com/v3/payments/{id}/returns",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'additionalInfo' => '<string>',
    'compensationAmount' => 123,
    'taxAmount' => 123
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "Idempotency-Key: <idempotency-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.pgw-sandbox.finventi.com/v3/payments/{id}/returns"

	payload := strings.NewReader("{\n  \"additionalInfo\": \"<string>\",\n  \"compensationAmount\": 123,\n  \"taxAmount\": 123\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "<idempotency-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.pgw-sandbox.finventi.com/v3/payments/{id}/returns")
  .header("Idempotency-Key", "<idempotency-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"additionalInfo\": \"<string>\",\n  \"compensationAmount\": 123,\n  \"taxAmount\": 123\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.pgw-sandbox.finventi.com/v3/payments/{id}/returns")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"additionalInfo\": \"<string>\",\n  \"compensationAmount\": 123,\n  \"taxAmount\": 123\n}"

response = http.request(request)
puts response.read_body

{
  "createdAt": "2025-11-21T12:46:54.321667Z",
  "creditor": {
    "account": {
      "iban": "<string>",
      "other": {
        "id": "<string>",
        "issuer": "<string>",
        "scheme": {
          "code": "<string>",
          "proprietary": "<string>"
        }
      }
    },
    "agent": {
      "bic": "DEMOLT1XXXX",
      "name": "<string>"
    },
    "address": {
      "country": "LT",
      "line": "<string>",
      "structured": {
        "buildingName": "<string>",
        "buildingNumber": "<string>",
        "countrySubDivision": "<string>",
        "department": "<string>",
        "districtName": "<string>",
        "floor": "<string>",
        "postBox": "<string>",
        "postCode": "<string>",
        "room": "<string>",
        "street": "<string>",
        "subDepartment": "<string>",
        "townLocationName": "<string>"
      },
      "town": "Vilnius"
    },
    "name": "<string>",
    "organisationIdentification": {
      "otherIdentifications": [
        {
          "id": "<string>",
          "issuer": "<string>",
          "scheme": {
            "code": "<string>",
            "proprietary": "<string>"
          }
        }
      ],
      "bic": "<string>",
      "lei": "<string>"
    },
    "privateIdentification": {
      "otherIdentifications": [
        {
          "id": "<string>",
          "issuer": "<string>",
          "scheme": {
            "code": "<string>",
            "proprietary": "<string>"
          }
        }
      ],
      "birthInformation": {
        "city": "<string>",
        "country": "<string>",
        "date": "<string>",
        "province": "<string>"
      }
    }
  },
  "debtor": {
    "account": {
      "iban": "<string>",
      "other": {
        "id": "<string>",
        "issuer": "<string>",
        "scheme": {
          "code": "<string>",
          "proprietary": "<string>"
        }
      }
    },
    "agent": {
      "bic": "DEMOLT1XXXX",
      "name": "<string>"
    },
    "address": {
      "country": "LT",
      "line": "<string>",
      "structured": {
        "buildingName": "<string>",
        "buildingNumber": "<string>",
        "countrySubDivision": "<string>",
        "department": "<string>",
        "districtName": "<string>",
        "floor": "<string>",
        "postBox": "<string>",
        "postCode": "<string>",
        "room": "<string>",
        "street": "<string>",
        "subDepartment": "<string>",
        "townLocationName": "<string>"
      },
      "town": "Vilnius"
    },
    "name": "<string>",
    "organisationIdentification": {
      "otherIdentifications": [
        {
          "id": "<string>",
          "issuer": "<string>",
          "scheme": {
            "code": "<string>",
            "proprietary": "<string>"
          }
        }
      ],
      "bic": "<string>",
      "lei": "<string>"
    },
    "privateIdentification": {
      "otherIdentifications": [
        {
          "id": "<string>",
          "issuer": "<string>",
          "scheme": {
            "code": "<string>",
            "proprietary": "<string>"
          }
        }
      ],
      "birthInformation": {
        "city": "<string>",
        "country": "<string>",
        "date": "<string>",
        "province": "<string>"
      }
    }
  },
  "direction": "OUTBOUND",
  "endToEndId": "<string>",
  "id": 10300007,
  "instructedAmount": 100,
  "instructedCurrency": "EUR",
  "metadata": [
    "<string>"
  ],
  "scheme": "SEPA_CT",
  "sddActionOptions": [
    {
      "reasons": [
        {
          "available": true,
          "code": "MD06",
          "deadline": "2026-10-15T11:15:00+03:00"
        }
      ],
      "type": "RETURN",
      "deadline": "2026-08-27T11:15:00+03:00",
      "settlementDate": "2023-12-25",
      "windowEndDate": "2026-12-25"
    }
  ],
  "sddRejectWindowExpired": true,
  "sddReturnWindowsExpired": true,
  "settlementAmount": 100,
  "settlementCurrency": "EUR",
  "status": "COMPLETED",
  "type": "PAYMENT",
  "adjustmentDisplayParties": {
    "creditor": {
      "account": "<string>",
      "bic": "<string>",
      "name": "<string>"
    },
    "debtor": {
      "account": "<string>",
      "bic": "<string>",
      "name": "<string>"
    }
  },
  "categoryPurposeCode": "BONU",
  "categoryPurposeProprietary": "<string>",
  "chargesAndAdjustments": {
    "compensation": 25,
    "returnCharges": 50,
    "unaccountedTax": 123
  },
  "creditTransferType": "CUSTOMER",
  "directDebit": {
    "amendmentIndicator": true,
    "amendmentInformationDetails": {
      "originalCreditorSchemeId": "<string>",
      "originalDebtorAccount": "<string>",
      "originalMandateId": "<string>"
    },
    "esignature": "<string>",
    "mandateId": "MANDATE-2026-001",
    "sequenceType": "RCUR",
    "signatureDate": "2026-01-15"
  },
  "instructionId": "<string>",
  "messageId": "<string>",
  "originBic": "<string>",
  "originName": "<string>",
  "originReasonCode": "AC04",
  "originReasonInfo": "<string>",
  "parentPaymentId": 123,
  "parentTransactionAmount": 123,
  "purpose": "Invoice #12345",
  "purposeCode": "<string>",
  "settlementDate": "2023-12-25",
  "statusReason": {
    "code": "ACSC",
    "message": "Accepted settlement completed"
  },
  "structuredReference": {
    "issuer": "ISO",
    "reference": "RF123456"
  },
  "swift": {
    "businessMessageId": "BIZ-MSG-001",
    "charges": {
      "items": [
        {
          "amount": 50,
          "currency": "EUR",
          "bic": "<string>"
        }
      ],
      "bearer": "SHAR"
    },
    "messageDefinition": "pacs.008.001.08",
    "receiverBic": "<string>",
    "senderBic": "<string>",
    "settlementAccount": {
      "currency": "EUR",
      "iban": "<string>",
      "other": {
        "id": "<string>",
        "issuer": "<string>",
        "scheme": {
          "code": "<string>",
          "proprietary": "<string>"
        }
      }
    },
    "settlementMethod": "INDA",
    "uetr": "<string>"
  },
  "t2": {
    "priority": "HIGH",
    "uetr": "a1b2c3d4-1111-4222-8333-000000000001"
  },
  "ultimateCreditor": {
    "name": "<string>",
    "organisationIdentification": {
      "otherIdentifications": [
        {
          "id": "<string>",
          "issuer": "<string>",
          "scheme": {
            "code": "<string>",
            "proprietary": "<string>"
          }
        }
      ],
      "bic": "<string>",
      "lei": "<string>"
    },
    "privateIdentification": {
      "otherIdentifications": [
        {
          "id": "<string>",
          "issuer": "<string>",
          "scheme": {
            "code": "<string>",
            "proprietary": "<string>"
          }
        }
      ],
      "birthInformation": {
        "city": "<string>",
        "country": "<string>",
        "date": "<string>",
        "province": "<string>"
      }
    }
  },
  "ultimateDebtor": {
    "name": "<string>",
    "organisationIdentification": {
      "otherIdentifications": [
        {
          "id": "<string>",
          "issuer": "<string>",
          "scheme": {
            "code": "<string>",
            "proprietary": "<string>"
          }
        }
      ],
      "bic": "<string>",
      "lei": "<string>"
    },
    "privateIdentification": {
      "otherIdentifications": [
        {
          "id": "<string>",
          "issuer": "<string>",
          "scheme": {
            "code": "<string>",
            "proprietary": "<string>"
          }
        }
      ],
      "birthInformation": {
        "city": "<string>",
        "country": "<string>",
        "date": "<string>",
        "province": "<string>"
      }
    }
  },
  "updatedAt": "2025-11-21T12:46:54.612954Z"
}

{
  "code": "<string>",
  "data": {
    "errors": [
      {
        "code": "<string>",
        "field_name": "<string>",
        "message": "<string>",
        "value": "<string>"
      }
    ],
    "message": "<string>"
  },
  "message": "<string>"
}

{
  "code": "<string>",
  "data": {
    "errors": [
      {
        "code": "<string>",
        "field_name": "<string>",
        "message": "<string>",
        "value": "<string>"
      }
    ],
    "message": "<string>"
  },
  "message": "<string>"
}

{
  "code": "<string>",
  "data": {
    "errors": [
      {
        "code": "<string>",
        "field_name": "<string>",
        "message": "<string>",
        "value": "<string>"
      }
    ],
    "message": "<string>"
  },
  "message": "<string>"
}

{
  "code": "<string>",
  "data": {
    "errors": [
      {
        "code": "<string>",
        "field_name": "<string>",
        "message": "<string>",
        "value": "<string>"
      }
    ],
    "message": "<string>"
  },
  "message": "<string>"
}

Overview

Use this endpoint when you need to return a completed inbound SWIFT payment to its originator. Returning a payment creates a separate Payment return transaction linked to the original payment. The original payment remains Completed, and the 201 response contains the newly created return transaction.

Requirements

The original payment must be an inbound SWIFT payment in Completed status.
The original payment must not have another return that has not been rejected.
The Idempotency-Key header must contain a UUID version 4 value.

Supported SWIFT return reasons

The reason field accepts these values for SWIFT payments:

AC01
AC04
AC06
AG01
BE04
BE08
CUST
DUPL
FRAD
MD07
NARR
RR04

The API uses one request model for multiple payment methods, but reason codes are validated against the original payment’s method. Codes documented for SEPA Credit Transfer, SEPA Direct Debit, or T2 are not automatically valid for SWIFT.

Additional reason information

Use additionalInfo to provide free-text return reason information, up to 105 characters.

When reason is NARR, additionalInfo is required and must not be blank.
For every other supported SWIFT reason, additionalInfo is optional.

Headers

Idempotency-Key

string

required

Unique UUID identifying this return request.

Path Parameters

integer<int64>

required

ID of the payment to return.

Body

application/json

reason

enum<string> | null

required

Return reason. The codes accepted depend on the payment method.

Available options:

AC01,

AC04,

AC06,

AG01,

AG02,

AM04,

AM05,

BE04,

BE05,

CNOR,

ERIN,

FF05,

FOCR,

MD01,

MD06,

MD07,

MS02,

MS03,

RC01,

RR01,

RR02,

RR03,

RR04,

SL01,

AM09,

BE01,

FRAD,

UPAY,

DUPL,

NARR,

RC03,

RC04,

INDM,

LEGL,

NOAS,

AGNT,

BE08,

CUST

additionalInfo

string | null

Free-text return reason. Applies only to SWIFT and T2, where it is mandatory when reason is NARR and optional otherwise. Ignored for SEPA Credit Transfer and SEPA Direct Debit.

Maximum string length: 105

compensationAmount

number | null

Compensation amount. SEPA Direct Debit only.

taxAmount

number | null

Tax amount. SEPA Direct Debit only.

Response

Payment return created

createdAt

string<date-time>

required

Time and date when the payment was created (UTC)

Example:

"2025-11-21T12:46:54.321667Z"

creditor

object

required

Creditor (recipient) party information

Show child attributes

debtor

object

required

Debtor (sender) party information

Show child attributes

direction

enum<string>

required

Payment direction

Available options:

OUTBOUND,

INBOUND

Example:

"OUTBOUND"

endToEndId

string

required

End-to-end identifier assigned by the originator

integer<int64>

required

Unique payment identifier

Example:

10300007

instructedAmount

integer

required

Instructed payment amount in minor currency units (cents)

Example:

100

instructedCurrency

string

required

Instructed payment currency ISO code

Example:

"EUR"

metadata

string[]

required

Client-defined metadata values assigned when the payment was created

scheme

enum<string>

required

Payment scheme. SEPA_CT — SEPA Credit Transfer, SEPA_INST — SEPA Instant Credit Transfer, SEPA_DD — SEPA Direct Debit, SWIFT — SWIFT cross-border payment.

Available options:

SEPA_CT,

SEPA_INST,

SEPA_DD,

SWIFT,

T2

Example:

"SEPA_CT"

sddActionOptions

object[]

required

R-transactions a client may raise against this payment right now. Empty for anything but a received SEPA direct debit collection. The action endpoints validate these windows again when a request is submitted.

Show child attributes

sddRejectWindowExpired

boolean

required

True only when all Reject reason windows have expired. False also covers unknown expiry.

sddReturnWindowsExpired

boolean

required

True only when all Return and Refund reason windows have expired. False also covers unknown expiry.

settlementAmount

integer

required

Settlement amount in minor currency units (cents)

Example:

100

settlementCurrency

string

required

Settlement currency ISO code

Example:

"EUR"

status

enum<string>

required

Current payment status

Available options:

CREATED,

TO_SIGN,

SIGNED,

SENT_TO_CLEAR,

COMPLETED,

CANCELLED,

REJECTED,

ACCEPTED,

SOME_PROBLEMS,

PENDING_CONFIRMATION

Example:

"COMPLETED"

type

enum<string>

required

Payment type

Available options:

PAYMENT,

PAYMENT_CANCELLATION,

PAYMENT_RETURN,

REVERSE_PAYMENT,

CSM_FEES,

ADJUSTMENT

Example:

"PAYMENT"

adjustmentDisplayParties

object | null

Display-only parties for a resolved liquidity adjustment; the authoritative parties remain in debtor and creditor

Show child attributes

categoryPurposeCode

enum<string> | null

Category purpose code (e.g. SALA, TAXS, GOVT)

Available options:

BONU,

CASH,

CBLK,

CCRD,

CORT,

DCRD,

DIVI,

DVPM,

EPAY,

FCIN,

FCOL,

GOVT,

HEDG,

ICCP,

IDCP,

INTC,

INTE,

LOAN,

MP2B,

MP2P,

OTHR,

PENS,

RPRE,

RRCT,

RVPM,

SALA,

SECU,

SSBE,

SUPP,

TAXS,

TRAD,

TREA,

VATX,

WHLD

categoryPurposeProprietary

string | null

Proprietary category purpose

chargesAndAdjustments

object | null

Return-only charges and adjustments. Populated only for payment_return / payment_cancellation transactions; absent otherwise.

Show child attributes

creditTransferType

enum<string> | null

Credit transfer type for T2 payments

Available options:

CUSTOMER,

FINANCIAL_INSTITUTION

directDebit

object | null

SEPA direct debit fields, present only for SDD payments

Show child attributes

instructionId

string | null

Instruction identifier

messageId

string | null

Message identifier

originBic

string | null

Return / rejection originator BIC

originName

string | null

Return / rejection originator name

originReasonCode

string | null

Return / rejection reason code

Example:

"AC04"

originReasonInfo

string | null

Return / rejection reason information

parentPaymentId

integer<int64> | null

Parent payment identifier, present for returns / reversals / cancellations

parentTransactionAmount

integer | null

Original (parent) transaction amount in minor currency units (cents)

purpose

string | null

Unstructured remittance information (free text)

Example:

"Invoice #12345"

purposeCode

string | null

ISO 20022 purpose code or proprietary purpose value (e.g. SUPP, SALA, TAXS)

settlementDate

string<date> | null

Settlement date

statusReason

object | null

Reason for the current status

Show child attributes

structuredReference

object | null

Structured remittance reference

Show child attributes

swift

object | null

SWIFT-specific fields, present only for SWIFT payments

Show child attributes

object | null

T2-specific fields, present only for T2 payments

Show child attributes

ultimateCreditor

object | null

Ultimate creditor party information

Show child attributes

ultimateDebtor

object | null

Ultimate debtor party information

Show child attributes

updatedAt

string<date-time> | null

Time and date when the payment was last updated (UTC)

Example:

"2025-11-21T12:46:54.612954Z"

Last modified on August 5, 2026

Getting Started

Integration Guide

Account Management

SEPA Instant/SCT

SEPA Direct Debit

SWIFT Payments

Payment Information

Investigations (Preview)

Nostro Accounts

Bank Information

Webhooks

Overview

Requirements

Supported SWIFT return reasons

Additional reason information

Headers

Path Parameters

Body

Response

​Overview

​Requirements

​Supported SWIFT return reasons

​Additional reason information

Headers

Path Parameters

Body

Response

Overview

Requirements

Supported SWIFT return reasons

Additional reason information