Skip to main content
Credit funds
This API MUST be implemented by the Partner. Platform’s backend will notify the final fund credit to the user’s account.
Our backend will consume this service by performing a POST request to: [Base-URL]/CreditFunds.
The path must be respected exactly as specified. The Partner defines only the [Base-URL]; the resource segment /CreditFunds, the POST method and the JSON body are fixed by this contract and are case-sensitive.Every request travels signed. It carries the X-Timestamp and X-Signature headers with the HMAC-SHA256 signature of the raw body. The Partner must validate the signature before processing the request.
Our service will check CreditResponseType configuration. If Sync, the response will be immediate. If Async, status will be checked by Get Credit Status endpoint.
This configuration must be agreed during the planning phase of the integration. If the Partner applies the credit immediately, Sync is used, this response carries the final outcome, and Get Credit Status does not need to be implemented.
Expected behavior: Payment order (credit) to a virtual network account. We will send a notification to indicate that funds should be settled in favor of an AccountIdentifier for the stipulated amount. The destination system must respond whether the action was successful (Success), returning a trace and/or the reason why it failed (NonCreditReason).
A Success: true response MUST carry a TrackingIdentifier. It is the only handle the Platform has on the credit movement, and it cannot be recovered afterwards. Without it the credit can no longer be polled through Get Credit Status nor undone through Reverse Credit Funds — under an Async configuration the Platform is left unable to confirm a credit the Partner already applied, and under Sync the credit becomes irreversible. Either way it has to be reconciled by hand with the Partner.If the credit fails, return Success: false with the corresponding NonCreditReason; that path does not require a TrackingIdentifier.

Headers

X-Timestamp
string
required

UTC timestamp in ISO-8601 format with milliseconds (yyyy-MM-ddTHH:mm:ss.fffZ), generated at send time. Its exact string value is part of the signed message, so it cannot be altered, and it lets the Partner reject stale requests (replay protection). See Data Integrity.

X-Signature
string
required

HMAC-SHA256 signature of the request, Base64-encoded (standard alphabet). It is computed over bytes(X-Timestamp) + bytes(".") + rawBodyBytes using the shared secret agreed for the integration. The Partner MUST validate it — with a constant-time comparison and over the raw body, before any deserialization — and reject the request if it does not match. See Data Integrity.

User-Agent
string
required

Fixed value VNA. Sent on every request. Some Partners' WAFs reject requests without a User-Agent, so the Platform always sets it explicitly; if the Partner filters by this header, this is the value to allow.

Body

application/json
TransactionId
string
required

Unique identifier of the request, used as an idempotency key. It is derived deterministically from the operation, the Partner and the action, so a retry of the same action arrives with the same value: the Partner MUST process it only once and return the original outcome on repeats.

AuthTrackingIdentifier
string
required

The TrackingIdentifier the Partner returned in the Tx Authorization response for this same transaction. It lets the Partner match the credit against the authorization it already approved.

AccountIdentifier
string
required

An Id representing the External Account Object for the Partner.

Amount
number<double>
required

Amount of the transaction, with TWO decimals.

Currency
string
required

Currency of the transaction, per ISO 4217. String of 3 chars.

ExchangeRate
number<double>
required

Exchange rate applied to the transaction.

Response

200 - application/json

Ok

Success
boolean
required

True if the CreditFunds is Successful / False if the CreditFunds Failed.

TrackingIdentifier
string
required

Identifier assigned by the Partner to the credit movement. Mandatory whenever Success is true — the Platform uses it to query the status (Get Credit Status) and to request a reversal (Reverse Credit Funds), so a successful credit returned without it leaves the operation unreconcilable and the Platform reports the transaction as failed even though the funds were applied.

NonCreditReason
enum<string>

If the credit is not successful, the reason should be sent, otherwise not sent. The text must be one of the fixed possible values.

  • None — no reason; the credit was not denied for any of the reasons below
  • AccountBlocked — the credit has been denied because the external account object is blocked
  • AccountBlockedByLaw — the credit has been denied because the external account object is blocked by legal reasons (e.g. litigation)
  • AccountBlockedByGovernment — the credit has been denied because the external account object is blocked due to government mandated reasons (e.g. fiscal)
  • ByVelocity — the credit has been denied because the external account object has reached the velocity limit defined in the Partner, this is, the amount of transactions in a specific lapse of time allowed by the partner
  • ByAmountLimit — the credit has been denied because the external account object has reached the transaction amount limit defined in the Partner system
  • ByAccumulateAmountLimit — the credit has been denied because the external account object has reached the accumulated amount limit defined in the Partner system
  • InvalidAccount — the credit has been denied because the account referenced is invalid
  • InvalidParameter — the credit has been denied because a parameter of the request is invalid
  • InvalidCurrency — the credit has been denied because the currency of the request is invalid
  • InvalidSenderData — the credit has been denied because the sender's personal data is invalid
  • InvalidDestinationData — the credit has been denied because the receiver's personal data is invalid
  • InvalidExchangeRate — the credit has been denied because the exchange rate provided is invalid
  • InvalidAmount — the credit has been denied because the amount is invalid
  • NotPreviouslyValidated — the credit has been denied because the account was not previously validated through a TxAuthorization request
  • InvalidReferenceId — the credit has been denied because the reference/tracking id provided is invalid
Available options:
None,
AccountBlocked,
AccountBlockedByLaw,
AccountBlockedByGovernment,
ByVelocity,
ByAmountLimit,
ByAccumulateAmountLimit,
InvalidAccount,
InvalidParameter,
InvalidCurrency,
InvalidSenderData,
InvalidDestinationData,
InvalidExchangeRate,
NotPreviouslyValidated,
InvalidReferenceId,
InvalidAmount