PIpismo
Funds recovery

Create funds recovery [beta]

Creates and establishes a new funds recovery to track and block diverted funds in Pix fraud cases.

The tracking follows the chain of subsequent transactions starting from the contested transaction.

DICT manages the entire process. You define the initial tracking_graph_parameters and DICT executes tracking, prioritization, and blocking, then opens the infraction notifications that the receiving PSPs analyze.

Notes:

  • The contested transaction must have occurred less than 80 days ago. This limit is the same for an original transaction and for a reversal transaction.
  • Only the payer of the contested transaction can create funds recovery. When contesting a reversal, the payer is the participant that sent the reversal — that is, the PSP of the party who received the original transaction.
  • root_transaction_id takes the end-to-end ID of the original transaction, or the reversal end-to-end ID when contesting a reversal.
  • A reversal issued to settle an operational flaw cannot be contested. If the refund behind the reversal had refund_reason of OPERATIONAL_FLAW, DICT rejects the funds recovery as ineligible. This is the only restriction on contesting a reversal.
  • When contesting a reversal, situation_type must be OTHER, which makes report_details mandatory.
  • Recipient PSPs have 7 calendar days to analyze infraction notifications
  • Refund must be initiated within 72 hours after analysis completion
  • Once refunding starts, the process cannot be cancelled

Terminology: the DICT operating manual refers to an original transaction as pacs.008 and to a reversal transaction as pacs.004.

Thie endpoint generates a Pix funds recovery status changed event.

For more information refer to Pix funds recovery.

post/v1/pix/funds-recoveries

Request

  • Base URL
    https://sandbox.pismolabs.io/pix-dict
  • URL
    https://sandbox.pismolabs.io/pix-dict/v1/pix/funds-recoveries
  • Auth
    HTTP bearer

Request body

root_transaction_idstring required

Identifier of the contested transaction, 32 characters.

  • Contesting an original transaction — its end-to-end ID, which begins with E.
  • Contesting a reversal transaction — its reversal end-to-end ID, which begins with D.
situation_type'SCAM' | 'ACCOUNT_TAKEOVER' | 'COERCION' | 'FRAUDULENT_ACCESS' | 'OTHER' | 'UNKNOWN' required

Situation type:

  • SCAM - Scam/fraud through social engineering
  • ACCOUNT_TAKEOVER - Unauthorized transaction without digital authentication
  • COERCION - Coercion crime (kidnapping, extortion)
  • FRAUDULENT_ACCESS - Fraudulent access and authorization (phishing, stolen password) |
  • OTHER - Other cases. This option REQUIRES you pass report_details.
  • UNKNOWN - Unknown state

When the contested transaction is a reversal, the DICT operating manual requires situation_type to be OTHER, which in turn makes report_details mandatory.

report_detailsstring

Details about report

Example request

{
  "root_transaction_id": "E1234567890123456789012345678901",
  "contact_information": {
    "phone": "551154874551",
    "email": "polly_ester@email.com"
  },
  "report_details": "Details that can help the receiving participant to analyze the suspected violation",
  "tracking_graph_parameters": {
    "hop_window": "PT2H",
    "max_hops": 5
  }
}

Response

Created - synchronous success

idstring

Funds recovery identifier.

Returned from the Create funds recovery endpoint.

status'CREATED' | 'AWAITING_ANALYSIS' | 'TRACKED' | 'ANALYSED' | 'REFUNDING' | 'COMPLETED' | 'CANCELLED'

Funds recovery status:

  • CREATED - Recovery created, awaiting next action.
  • TRACKED - The transaction tracking graph has been created.
  • AWAITING_ANALYSIS - Awaiting analysis from receiver PSPs (deadline: 7 calendar days).
  • ANALYSED - Analysis completed, ready for refund.
  • REFUNDING - Refund process in progress.
  • COMPLETED - Recovery successfully completed.
  • CANCELLED - Recovery cancelled.
root_transaction_idstring

Identifier of the contested transaction, 32 characters.

  • Contesting an original transaction — its end-to-end ID, which begins with E.
  • Contesting a reversal transaction — its reversal end-to-end ID, which begins with D.
situation_type'SCAM' | 'ACCOUNT_TAKEOVER' | 'COERCION' | 'FRAUDULENT_ACCESS' | 'OTHER' | 'UNKNOWN'

Situation type:

  • SCAM - Scam/fraud through social engineering
  • ACCOUNT_TAKEOVER - Unauthorized transaction without digital authentication
  • COERCION - Coercion crime (kidnapping, extortion)
  • FRAUDULENT_ACCESS - Fraudulent access and authorization (phishing, stolen password) |
  • OTHER - Other cases. This option REQUIRES you pass report_details.
  • UNKNOWN - Unknown state

When the contested transaction is a reversal, the DICT operating manual requires situation_type to be OTHER, which in turn makes report_details mandatory.

reporter_participantstring

Reporter participant ID

report_detailsstring

Details about report

created_atstring date-time

Creation datetime. A RFC 3339 date-time value. For example - 2023-04-12T23:20:50.52Z.

updated_atstring date-time

Updated datetime. A RFC 3339 date-time value. For example - 2023-04-12T23:20:50.52Z.

Example response

{
  "id": "53D0F66A-BAB0-49D7-B7DC-807B82AABD8D",
  "status": "CREATED",
  "root_transaction_id": "E1234567890123456789012345678901",
  "reporter_participant": "12345678",
  "contact_information": {
    "phone": "551154874551",
    "email": "polly_ester@email.com"
  },
  "report_details": "Details that can help the receiving participant to analyze the suspected violation",
  "created_at": "2020-08-13T13:49:03Z",
  "updated_at": "2020-08-13T13:49:03Z"
}

Changes

No recorded changes to this operation across all 1 revision of this API.