Quickstart Guide
Welcome to the Goya Developer Portal! This guide will walk you through the essential steps to integrate with our APIs , including authentication, creating entities, and submitting factoring data.
Base URLs
Authentication URL (Sandbox)
https://goyahealth-uat.eu.auth0.comBase URL (Sandbox)
https://platform.goya.finance/uatObtain a Subscription Key
To access Goya APIs, you need to subscribe to a product and retrieve your subscription key. Follow these steps:
Navigate to the Our APIs Page
Log in to the Goya Developer Portal and go to the Our APIs section.Select a Product
Choose the product you want to subscribe to (e.g., Factoring API (Sandbox)).Create a Subscription
In the Your Subscriptions section of the product page:Enter a name for your subscription (e.g., "Test App" or "Integration Key").
Click the Subscribe button.
Access Your Subscription Key
After subscribing, you'll be redirected to your Profile page. There you can:View and rename all your active subscriptions.
Copy your subscription key.
Regenerate or cancel a key if needed.
Create a Client
Clients are created through a manual provisioning process. Please contact us for getting a Client. We will return you a client_id and client_secret.
Authenticate & Obtain a Token
Goya uses OAuth 2.0 for secure authentication and authorization. Use your client_id and client_secret to retrieve an access token:
curl --request POST \--url https://goyahealth-uat.eu.auth0.com/oauth/token \--header 'content-type: application/json' \--data '{"client_id": "<your_client_id>","client_secret": "<your_client_secret>","audience": "https://platform.goya.finance/backend","grant_type": "client_credentials"}'
Example response
{"access_token": "<your_access_token>","scope": "debtor_write debtor_read creditor_write creditor_read invoice_write invoice_read","expires_in": 86400,"token_type": "Bearer"}
Factoring API
Create a Creditor
Once authenticated, use your Bearer token and subscription key to create a creditor.
⚠️ Each client is tied to a specific factoring type (Full factoring or In-house) and can only create entities relevant to that type.
Creditors are initially set to PENDING and updated to ACTIVE by Goya upon approval.
Example: Create a creditor
curl --request POST \--url https://platform.goya.finance/uat/factoring/v1/creditors \--header 'authorization: Bearer <your_access_token>' \--header 'ocp-apim-subscription-key: <your_subscription_key>' \--header 'content-type: application/json' \--data '{"externalCreditorId": "1234","name": "John Doe Inc.","street": "Foo avenue 123","postcode": "4711","city": "Berlin","countryCode": "DE","legalEntity": "GmbH","industrySector": "010","codeLEI": "1223","registrationCourt": "DE123","registrationNumber": "D111","federalBankId": "BNK1","federalBankKNEId": "B1111","incorporationDate": "2024-05-19","taxNumber": "00/001/00001","vatId": "","numberOfEmployees": 100,"numberOfEmployeesDate": "2024-05-04","balanceSheetTotal": null,"paymentIBAN": "DE12222221312312","requestedLimit": {"amountCents": 5000000,"currency": "EUR","from": "2025-05-04","to": "2026-05-04"}}'
Create a Debtor
Debtors must be associated with exactly one ACTIVE creditor. Debtors are created in the PENDING state and will be transitioned to ACTIVE upon approval.
⚠️ Attempting to associate a debtor with anINACTIVEorPENDINGcreditor will result in a failed request.
Heads-up: A debtor can transition between states (PENDING,ACTIVE,BLOCKED). Ensure proper handling in your application logic.
Example: Create a debtor
curl --request POST \--url https://platform.goya.finance/uat/factoring/v1/debtors \--header 'authorization: Bearer <your_access_token>' \--header 'ocp-apim-subscription-key: <your_subscription_key>' \--header 'content-type: application/json' \--data '{"externalDebtorId": "Ext Id 1","creditorId": "1be18b9f-61a5-4320-899c-d957f75345d0","externalCreditorId":"1234","name": "Max Mustermann","street": "Schwallstraße 13","postcode": "10115","city": "Berlin","countryCode": "DE","legalType": "B2C","legalEntity": null,"industrySector": null,"codeLEI": null,"registrationCourt": null,"registrationNumber": null,"federalBankId": null,"federalBankKNEId": null,"incorporationDate": null,"taxNumber": null,"vatId": null,"numberOfEmployees": null,"numberOfEmployeesDate": null,"balanceSheetTotal": null,"requestedLimit": {"amountCents": 200000,"currency": "EUR","from": "2025-05-04","to": "2026-12-04"}}'
Submit Factoring Data
Depending on your client type, you’ll use one of the following submission methods:
Submit an Invoice (Full Factoring Only)
Requires:
ACTIVEcreditorACTIVEdebtor
Response includes invoice ID and different status fields that indicate the processing of the invoice, such as:
IN_PROCESS,PURCHASED,PAID, etc.
Example: Submit an invoice (Full Factoring)
curl --request POST \--url https://platform.goya.finance/uat/factoring/v1/invoices \--header 'authorization: Bearer <your_access_token>' \--header 'ocp-apim-subscription-key: <your_subscription_key>' \--header 'content-type: application/json' \--data '{"creditorId": "040bc70f-ab12-49b5-a179-64d8b6be7344","debtorId": "8cfb7044-0670-41bd-a69c-b331439cbfbf","totalAmountCents": 12399,"currency": "EUR","invoiceNumber": "M70001-25-00020","date": "2025-04-07","dueDate": "2025-05-07","vatItems": []}'
Invoice response
{"id": "0b8c0533-97f2-44b7-883f-ef7cd881e576","creditorId": "1be18b9f-61a5-4320-899c-d957f75345d0","externalCreditorId": "1234","debtorId": "8ccf1e0e-ff89-4822-b977-2ee5468ae35a","externalDebtorId": "Ext Id 1","invoiceNumber": "M70001-25-00020","currency": "EUR","totalAmountCents": 12399,"date": "2025-04-07","dueDate": "2025-05-07","vatItems": [],"status": {"overall": "IN_PROCESS","paid": "NOT_AVAILABLE","settled": "NOT_AVAILABLE","purchased": "NOT_AVAILABLE","dunningLevel": "NOT_AVAILABLE"}}
Submit Open Items List (In-house Factoring Only)
Requires:
ACTIVEcreditorAll debtors in the list must be
ACTIVE
Returns a record of submitted open items.
Example: Submit open items list (In-house Factoring)
curl --request POST \--url https://platform.goya.finance/uat/factoring/v1/open-items \--header 'authorization: Bearer <your_access_token>' \--header 'ocp-apim-subscription-key: <your_subscription_key>' \--header 'content-type: application/json' \--data '{"creditorId": "1be18b9f-61a5-4320-899c-d957f75345d0","externalCreditorId": "","accountStatementNumber": "2/1","opList": [{"debtorId": "8ccf1e0e-ff89-4822-b977-2ee5468ae35a","externalDebtorId": "","type": "INVOICE","totalAmountCents": 10000,"openAmountCents": 10000,"currency": "EUR","number": "M80070-25-00001","date": "2025-05-12","dueDate": "2025-06-12","dispute": false,"vatItems": []},{"debtorId": "22cc9672-f40b-4be5-b7c3-f4316f74d961","externalDebtorId": "","type": "INVOICE","totalAmountCents": 5000,"openAmountCents": 5000,"currency": "EUR","number": "M80070-25-00002","date": "2025-05-12","dueDate": "2025-06-12","dispute": false,"vatItems": []}]}'
Open items list response
{"id": "354e641c-9926-4ebf-9acc-04348013a120","creditorId": "1be18b9f-61a5-4320-899c-d957f75345d0","externalCreditorId": "","accountStatementNumber": "2/1","opList": [{"debtorId": "8ccf1e0e-ff89-4822-b977-2ee5468ae35a","externalDebtorId": "Ext Id 1","type": "INVOICE","totalAmountCents": 10000,"openAmountCents": 10000,"currency": "EUR","number": "M80070-25-00001","date": "2025-05-12","dueDate": "2025-06-12","dispute": false,"vatItems": []},{"debtorId": "22cc9672-f40b-4be5-b7c3-f4316f74d961","externalDebtorId": "Ext Id 2","type": "INVOICE","totalAmountCents": 5000,"openAmountCents": 5000,"currency": "EUR","number": "M80070-25-00002","date": "2025-05-12","dueDate": "2025-06-12","dispute": false,"vatItems": []}]}
Summary & Best Practices
Always check for entity status (
ACTIVE) before creating dependent resources.Store tokens securely and refresh them before expiry (
expires_in= 86400 seconds).Validate all mandatory fields before submitting requests.
